How to Install Wiki.js on Debian 12

Ready to take control of your organization’s knowledge base? Dive into the world of self-hosted documentation with Wiki.js, a powerful and flexible open-source wiki software built on Node.js, Git, and Markdown. This comprehensive guide provides a step-by-step walkthrough to install Wiki.js on a Debian 12 server, leveraging PostgreSQL for robust data management, Nginx as a high-performance reverse proxy, and securing your instance with free SSL/TLS certificates from Let’s Encrypt. Discover how to build a customizable, resource-efficient knowledge hub that perfectly aligns with your technical stack.

Why Choose Wiki.js for Your Self-Hosted Documentation?

Wiki.js stands out as a free and open-source documentation platform, powered by Node.js, Git, and Markdown. Released under the AGPL-v3 License, it’s engineered for optimal performance and efficient resource conservation, making it an ideal choice for a self-hosted wiki. Its versatility allows deployment across various environments, from traditional operating systems to modern container platforms like Docker and Kubernetes, and even cloud services such as Heroku. Beyond its core, Wiki.js boasts compatibility with PostgreSQL and offers over 50 integrations for enhanced authentication, logging, search, rendering, and storage. With intuitive interfaces for both administrators and users, coupled with extensive customization options, Wiki.js is the perfect solution for thoroughly documenting your tech stack.

Prerequisites for Your Debian 12 Wiki.js Server

Before embarking on your Wiki.js installation, ensure your Debian server setup is ready. You’ll need:

• A Debian 12 server.
• A non-root user with administrator privileges.
• A domain name is pointed to your server’s IP address. This example will use the domain wiki.howtoforge.local.

Setting Up Core Dependencies for Wiki.js

Essential Packages for Your Debian Server Setup

The initial step in your Debian server setup involves installing critical dependencies required for Wiki.js. These include:

• PostgreSQL database server: The robust backend for your Wiki.js data.
• Nginx web server: Serving as a high-performance reverse proxy for your Wiki.js instance.
• Node.js and NPM: The indispensable JavaScript runtime engine and its package manager.
• Certbot and Nginx Certbot Plugin: For seamless generation of SSL/TLS certificates via Let’s Encrypt and automatic Nginx configuration for HTTPS.

Begin by updating your Debian package repository:

sudo apt update

Next, install all necessary packages with a single command:

sudo apt install postgresql postgresql-common nodejs npm nginx certbot python3-certbot-nginx

Confirm the installation by typing y when prompted.

Verifying Your Service Installations

After installation, it’s crucial to verify that all services are running and enabled correctly.
Check PostgreSQL status:

sudo systemctl is-enabled postgresql

sudo systemctl status postgresql

You should see output indicating the service is active and enabled.

Confirm Nginx is active and running:

sudo systemctl is-enabled nginx

sudo systemctl status nginx

Successful output will show Nginx as running and enabled.

Finally, verify Node.js and NPM versions:

node --version

npm --version

This will display the installed Node.js and NPM versions, confirming their presence.

Preparing Your PostgreSQL Database

Creating a Dedicated Database and User

With dependencies in place, the next crucial step for your self-hosted wiki is preparing the PostgreSQL database. Log into PostgreSQL as the postgres user using the psql client:

sudo -u postgres psql

Once connected, execute these queries to create a new user (wikijs) and a database (wikijs) owned by that user. Remember to replace 'p4ssw0rd' with a strong, unique password:

CREATE USER wikijs WITH PASSWORD 'p4ssw0rd';

CREATE DATABASE wikijs OWNER wikijs;

To confirm the database and user creation, list all users and databases:

\du

\l

You should now see the wikijs user and database listed. Type quit to exit PostgreSQL.

Deploying Wiki.js: Download and Configuration

Downloading the Wiki.js Source Code

Now, let’s get the Wiki.js application onto your server. First, create a dedicated system user (wikijs) that will run the application for enhanced security:

sudo useradd -m -s /bin/false wikijs

Next, create the installation directory, navigate into it, and download the latest Wiki.js source code:

mkdir -p /opt/wikijs; cd /opt/wikijs

wget https://github.com/Requarks/wiki/releases/latest/download/wiki-js.tar.gz

After downloading, extract the archive and set the correct ownership for the /opt/wikijs directory to your newly created wikijs user:

tar -xf wiki-js.tar.gz

sudo chown -R wikijs:wikijs /opt/wikijs

Tailoring Your Wiki.js Configuration

With the Wiki.js files in place, it’s time to configure the application to connect with your PostgreSQL database and define its binding address. Copy the sample configuration file and open it for editing as the wikijs user:

sudo -u wikijs cp config.sample.yml config.yml

sudo -u wikijs nano config.yml

Locate the database configuration section and update it with your PostgreSQL credentials. Ensure host is localhost and replace 'p4ssw0rd' with the password you set earlier:

# PostgreSQL / MySQL / MariaDB / MS SQL Server only:
  host: localhost
  port: 5432
  user: wikijs
  pass: p4ssw0rd
  db: wikijs
  ssl: false

Also, change the bindIP option to 127.0.0.1 to ensure Wiki.js listens only on the local interface, as Nginx will act as the public-facing proxy:

bindIP: 127.0.0.1

Save and exit the editor. To perform an initial test run of your Wiki.js installation, execute:

sudo -u wikijs node server

You should see confirmation that Wiki.js is running on localhost at port 3000. Press Ctrl+c to stop the process.

Ensuring High Availability: Running Wiki.js as a Systemd Service

For a reliable open-source documentation platform, Wiki.js needs to run consistently in the background. We’ll achieve this by setting it up as a systemd service, allowing for easy management via the systemctl utility.
Create a new systemd service file at /etc/systemd/system/wikijs.service:

sudo nano /etc/systemd/system/wikijs.service

Paste the following configuration, which defines how Wiki.js will run as a persistent background service:

[Unit]
Description=Wiki.js
After=network.target postgresql.service

[Service]
Type=simple
ExecStart=/usr/bin/node server
Restart=always
User=wikijs
Environment=NODE_ENV=production
WorkingDirectory=/opt/wikijs

[Install]
WantedBy=multi-user.target

Save and close the file. Now, reload the systemd manager to recognize the new service:

sudo systemctl daemon-reload

Start and enable the Wiki.js service to ensure it runs automatically at boot and continues operating on localhost port 3000:

sudo systemctl start wikijs

sudo systemctl enable wikijs

Verify the service status to confirm it’s running as expected:

sudo systemctl status wikijs

You should see output confirming the service is active and running. Finally, check that port 3000 is being utilized by the Node.js application:

ss -tulpn | grep 3000

This confirms Wiki.js is actively listening on its designated port.

Nginx: Your Powerful Reverse Proxy for Wiki.js

With Wiki.js gracefully running on localhost:3000, Nginx steps in as your public-facing reverse proxy. This not only improves performance and security but also allows you to serve Wiki.js on a standard web port (80/443). Ensure your domain name is already pointing to your server’s IP address.
Create a new Nginx server block configuration file at /etc/nginx/sites-available/wikijs:

sudo nano /etc/nginx/sites-available/wikijs

Insert the following configuration, making sure to replace wiki.howtoforge.local with your actual domain name:

server {
    listen 80;
    server_name wiki.howtoforge.local;
    root /opt/wikijs;
    access_log  /var/log/nginx/wikijs.access.log;
    error_log   /var/log/nginx/wikijs.error.log;

    location / {
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $http_host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://127.0.0.1:3000;
    }
}

Save and exit the editor. Now, enable the Nginx server block by creating a symbolic link and then test the Nginx configuration for syntax errors:

sudo ln -s /etc/nginx/sites-available/wikijs /etc/nginx/sites-enabled

sudo nginx -t

A successful test will output syntax is ok. Finally, restart Nginx to apply the new configuration:

sudo systemctl restart nginx

Open your web browser and navigate to your Wiki.js domain (e.g., http://wiki.howtoforge.local). You should now see the Wiki.js installation page.

Fortifying Security with Let’s Encrypt SSL/TLS

Securing your self-hosted wiki with SSL/TLS certificates is paramount for data integrity and user trust. We’ll use Certbot and Let’s Encrypt to obtain free certificates and automatically configure Nginx for HTTPS, including an automatic redirect from HTTP to HTTPS.
Execute the following command, replacing [email protected] with your actual email and wiki.howtoforge.local with your domain name:

sudo certbot --nginx --agree-tos --redirect --hsts --staple-ocsp --email [email protected] -d wiki.howtoforge.local

Upon successful completion, your SSL certificates will be generated and stored in the /etc/letsencrypt/live/wiki.howtoforge.local/ directory. Certbot’s Nginx plugin will automatically update your Nginx server block to enforce HTTPS.

Completing Your Wiki.js Installation and Initial Setup

Return to your web browser and revisit your Wiki.js domain (e.g., https://wiki.howtoforge.local). You should now be automatically redirected to a secure HTTPS connection.
Proceed to create your Wiki.js administrator account by entering your desired email address and a strong password. Click INSTALL to finalize the initial setup.
Upon successful installation, you’ll be directed to the Wiki.js login page. Enter your newly created admin credentials and click LOGIN.
The welcome page signifies a successful installation of your open-source documentation platform. From here, you can begin crafting your content or explore the comprehensive Wiki.js administration dashboard.
Navigate to the ADMINISTRATION section, then click on System Info under the SYSTEM menu. Here, you can verify your Wiki.js version (e.g., 2.5) and the Node.js (e.g., 18.x) and PostgreSQL (e.g., 15.x) versions powering your installation.

Final Thoughts on Your New Open-Source Documentation Platform

Congratulations! You have successfully navigated every step to install Wiki.js on your Debian 12 server. Your robust Debian server setup now hosts a powerful Wiki.js instance, complete with a PostgreSQL database, an efficient Nginx reverse proxy, and enterprise-grade security via Let’s Encrypt SSL/TLS certificates. You are now equipped to leverage this exceptional open-source documentation platform for all your knowledge management needs.

FAQ

• Question 1: Why is Nginx used as a reverse proxy for Wiki.js instead of direct access?
  • Answer 1: Using Nginx as a reverse proxy offers several critical benefits for a self-hosted wiki. It allows Wiki.js to run securely on a local port (like 3000) while Nginx handles public traffic on standard web ports (80/443). Nginx excels at load balancing, caching, and provides a powerful layer for implementing SSL/TLS encryption (as demonstrated with Let’s Encrypt) and other security features, offloading these tasks from the application itself.
• Question 2: Can I use a different database system for Wiki.js other than PostgreSQL?
  • Answer 2: Yes, Wiki.js is highly flexible with its database compatibility. While this guide focuses on PostgreSQL for its robustness and widespread adoption, Wiki.js also supports MySQL, MariaDB, and MS SQL Server. The configuration steps in config.yml would be adjusted accordingly to point to your chosen database type and credentials.
• Question 3: What are the key advantages of self-hosting Wiki.js compared to a cloud-based wiki service?
  • Answer 3: Self-hosting Wiki.js provides unparalleled control and customization. You own all your data, eliminating vendor lock-in and potential subscription costs. It offers full control over security, privacy, and system resources, making it ideal for sensitive internal documentation. While it requires initial setup and maintenance, the long-term benefits of sovereignty over your open-source documentation platform are significant.
    Unique Tip: For any self-hosted application like Wiki.js, implementing a regular, automated backup strategy for both the Wiki.js data directory (/opt/wikijs) and the PostgreSQL database is crucial. Tools like pg_dump for PostgreSQL and simple rsync or cron jobs for file backups can ensure your valuable documentation is always recoverable.

Read the original article