Wiki.js is fully modular, which allows any developer to write their own module or theme.
There are 2 methods to develop for Wiki.js. You can either use the dockerized development environment (recommended) or install all dependencies manually on your machine.
Developing on Docker for Windows
The instructions and commands below are made using
makeand unix-based commands. They will not work on Windows. While you can port these commands to their Windows equivalent, they will not be provided here. It's recommended that you use the Windows Subsystem for Linux (WSL) if you wish to use the commands below. It provides a native GNU/Linux environment without the overhead of a virtual machine.
Otherwise, consider using the non-docker instructions.
make docker-dev-up # You may need to start the above command with `sudo` depending on your OS configuration.
When you're done and no longer need the development environment. Simply run the following command to stop and remove the containers:
make docker-dev-down # You may need to start the above command with `sudo` depending on your OS configuration.
|docker-dev-up||Starts the development environment.|
|docker-dev-down||Stops and remove the development environment.|
|docker-dev-clean||Flush DB and cache. (Must run
|docker-dev-rebuild||Rebuilds the wiki container image. (Must run
|docker-build||Builds the client assets files using a temporary environment.|
The default docker environment is using PostgreSQL as the database engine. However it's sometimes useful to debug using other database engines. You can switch to any of the supported engines (
sqlite) by adding the
DEVDB variable at the end of any of commands above, e.g.:
make docker-dev-up DEVDB=mariadb make docker-dev-rebuild DEVDB=mssql
Make sure to shutdown any running instances BEFORE switching engines and then REBUILD the wiki image using
make docker-dev-rebuild. Otherwise Wiki.js will still use the old configuration file and connect to the previous database configuration.
The MS SQL image does not allow for a default database to be created by default. To create the database, you must:
make docker-dev-up DEVDB=mssql
make docker-dev-clean DEVDB=mssql
make docker-dev-up DEVDB=mssqlagain
Alternatively, you can also use Microsoft SQL Management Studio to connect to the container and create the initial database.
Production docker images can be built using the following command:
docker build -t requarks/wiki -f dev/build/Dockerfile .
Multi-architecture images for arm64 and arm/v7 can be built using the Docker experimental buildx plugin and QEMU. You can read more about how it works in this article.
docker buildx build --platform linux/arm64,linux/arm/v7 -t requarks/wiki --push -f dev/build/Dockerfile .
npm i -g yarn)
apt-get install build-essential
npm i -g --production windows-build-tools
config.ymlwith your local dev machine settings (db, redis, etc.)
From the project folder, simply run
This will start Wiki.js in dev mode. Client assets are compiled first (using Webpack), then the server will start automatically. Wait for this process to complete before loading the app!
Browse to the site, using the configuration you defined in
config.yml. For example, if using port 3000 on your local machine, you would browse to http://localhost:3000/.
The first time you load the wiki, you'll get greeted with the setup wizard. Complete all the steps to finish the installation.
Once you're ready to deploy your changes, you need to build the client assets into a production optimized bundle:
Wiki.js is built using Visual Studio Code and comes with pre-defined extension recommendations, project settings and debug configuration. You can use your favorite IDE but Visual Studio Code is highly recommended.
Any changes made to client files will automatically trigger a build and the site will be updated live automatically. If the changes cannot be replaced inline, the page will reload automatically.
Any changes made to the server files will automatically trigger a server restart. You can also force a restart by typing
rs in the terminal followed by Enter.
To stop the development server, use CTRL-C until the process exits.