Why self-host Wiki.js on a VPS
Wiki.js stands out for its ability to treat each page as a Markdown file synchronized with Git: your documentation becomes a versioned repository where every change is traceable and reversible. This plain-text storage approach protects you from proprietary lock-in, provided you control the infrastructure. On a VPS, you connect Wiki.js to your own GitHub or GitLab repository, choose your storage engine (PostgreSQL recommended), and enable the modules of your choice: LDAP authentication, comments, advanced search. Unlike a SaaS, nothing limits the number of pages, editors or spaces, and you can host several wikis on the same server thanks to the reverse proxy.
The benefits of a self-hosted Wiki.js
- Native Git versioning: each page is a Markdown file synchronized with your repository.
- Visual and Markdown editor of your choice, with real-time preview and syntax highlighting.
- Multiple authentication modules: local, LDAP, OAuth2, SAML, all configurable from the admin side.
- Built-in search with several engines (database, Elasticsearch) depending on your load.
- Fine-grained permission management by folder and by group, ideal for compartmentalizing internal documentation.
- Multi-wiki hosting on a single VPS via subdomains and a single reverse proxy.
Hardware and software requirements
Wiki.js is lightweight: 1 vCPU and 2 GB of RAM are enough for a read-heavy team wiki, since the Node.js engine stays frugal. Plan for an additional 2 GB of RAM if you enable Elasticsearch for large-scale full-text search. Disk usage depends mostly on attachments; 10 to 20 GB make a sound baseline. On the software side: Docker and docker compose v2, a domain or subdomain pointed at the VPS (docs.yourcompany.com), and a dedicated PostgreSQL 12+. If you want Git synchronization, prepare a deployment SSH key with write access to your repository before the first launch.
Deploy Wiki.js step by step
Provision the VPS and Docker
After updating the system, install Docker and the compose plugin. Create /opt/wikijs and a docker-compose.yml file. Wiki.js needs a database: we will declare PostgreSQL in the same stack.
Declare PostgreSQL and Wiki.js
Define a db service with the postgres:15 image, a persistent volume and the variables POSTGRES_DB=wiki, POSTGRES_USER, POSTGRES_PASSWORD. Add the wiki service with the ghcr.io/requarks/wiki:2 image and link it to the database via DB_TYPE=postgres and DB_HOST=db.
Launch and access the setup wizard
Start with docker compose up -d. Wiki.js automatically applies its migrations on first boot. Open port 3000 internally and access the wizard, which asks for the administrator's email and password.
Configure the reverse proxy and SSL
Place Caddy or Nginx in front of Wiki.js. With Nginx, create a vhost for docs.yourcompany.com that proxies to localhost:3000 and use certbot to obtain the Let's Encrypt certificate. Then set the canonical URL in the Wiki.js administration.
Connect Git synchronization
In Administration > Storage, enable the Git module, paste your repository's SSH URL and the deployment key. Choose bidirectional mode so that each edit pushes a commit, ensuring a versioned history of the entire documentation.
Enable Git storage in bidirectional mode but configure a dedicated machine account with its own committer name. You get a clean history where each page modified in the interface generates a commit attributed to the wiki, which makes documentation audits easier and lets you restore an earlier version with a simple git revert.
The official documentation
For advanced configuration and options specific to the tool, refer to the official Wiki.js documentation. This guide covers going live on a VPS; the vendor documentation remains the reference for fine-tuning, major updates and specific use cases.
