Overview

It's very easy to run a development instance of Wiki.js with all the necessary dependencies and tools included.

Requirements

Note

Avoid Docker Desktop on Linux as it's known to cause issues. Install the Docker Engine directly instead.

Basic Usage

Warning

All instructions below are written with Visual Studio Code in mind. The steps will defer for other editors.

  1. Clone the project on your local machine.
  2. Open the project in Visual Studio Code.
  3. Reopen the project in container (from the popup in the lower-right corner of the screen when opening the project, or via the Command Palette (Ctrl + Shift + P or F1) afterwards).
  4. Once in container mode, make a copy of config.sample.yml and rename it to config.yml. There's no need to edit the file, the default values are ok.
  5. Two terminals should automatically launch in the lower part of the screen. If this isn't the case, from the Command Palette, run the task "Create terminals":
    1. Launch the Command Palette (Ctrl + Shift + P or F1)
    2. Type Run Task and press Enter
    3. Select the task "Create terminals" and press Enter
  6. In the right-side terminal (Frontend), run the command:
    npm run build
  7. In the left-side terminal (Backend), run the command:
    npm run start
  8. Open your browser to http://localhost:3000
  9. Login using the default administrator user:

Populate Sample Content

A tool to quickly generate sample content is available in the Administration Area > Utilities page.

Backend Development

Tip

If you're still running the npm run start command, stop it first.

From the left-side terminal (Backend), run the command:

npm run dev

This will launch the server in dev mode and automatically restart upon modification of any server files.

Only precompiled client assets are served in this mode. See the sections below on how to modify the frontend and run in SPA (Single Page Application) mode.

Frontend Development

Important

Make sure you are running npm run dev in the left-side terminal (Backend) first! Requests still need to be forwarded to the server, even in SPA mode!

If you wish to modify any frontend content (under /frontend), you need to start the Vite Dev Server in the right-side terminal (Frontend):

npm run dev

You can then access the site at http://localhost:3001. Notice the port being 3001 rather than 3000. The app runs in a SPA (single-page application) mode and automatically hot-reload any modified component. Any requests made to the /_api endpoint are automatically forwarded to the server running on port 3000, which is why both must be running at the same time.

Any change you make to the frontend will not be reflected on port 3000 until you run the command npm run build in the right-side terminal.

Included Tools

pgAdmin

A web version of pgAdmin (a PostgreSQL administration tool) is available at http://localhost:8000. Use the login [email protected] / 123123 to login.

Add a new server with the following settings:

Mailpit

An instance of mailpit (an email testing tool) is available at http://localhost:8025.

In your Wiki.js dev instance, on the Administration Area > Mail page, enter the following settings to point to it: