Self-Host Vikunja To-Do List Web App

Vikunja is an open-source to-do list web app, which is developed with Go and Vue.

0. Environment

Software	Version
Ubuntu	24.04.1 LTS
OpenSSL	3.0.13
Snap	2.65
Nginx	1.24.0
Docker	27.3.1 (install later)
Certbot	2.11.0 (install later)

1. Install Docker

Please refer to the instructions in the Self-Host Maybe Finance Web App - 1. Install Docker section.

2. Setup Docker Compose

Vikunja is available via many different methods. In this guide, we plan to use Docker Compose to manage the Vikunja service and its dependencies.

2.1. Prepare for environment variables

mkdir -p ~/app/todolist
cd ~/app/todolist
touch .env
openssl rand -hex 64 > .env

The generated hexadecimal string will be used as the secret key of Vikunja service.

Update your .env file with the following content:

VIKUNJA_SERVICE_JWTSECRET="your_generated_very_long_hex_secret"
VIKUNJA_DATABASE_PASSWORD="your_postgres_password"

2.2. Configure Docker Compose file

cd ~/app/todolist
sudo mkdir -p /var/app/vikunja/app-data
sudo mkdir -p /var/app/vikunja/postgres-data

sudo chown -R 1000 /var/app/vikunja/app-data
sudo chown -R 1000 /var/app/vikunja/postgres-data

touch compose.yml

Update your compose.yml file with the following content:

services:
  vikunja:
    image: vikunja/vikunja:latest
    environment:
      VIKUNJA_SERVICE_PUBLICURL: "Your_Public_IP_or_Domain"
      VIKUNJA_DATABASE_HOST: db
      VIKUNJA_DATABASE_PASSWORD: ${VIKUNJA_DATABASE_PASSWORD:?}
      VIKUNJA_DATABASE_TYPE: postgres
      VIKUNJA_DATABASE_USER: vikunja
      VIKUNJA_DATABASE_DATABASE: vikunja
      VIKUNJA_SERVICE_JWTSECRET: ${VIKUNJA_SERVICE_JWTSECRET:?}
    ports:
      - 3456:3456
    volumes:
      - /var/app/vikunja/app-data:/app/vikunja/files
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped

  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: ${VIKUNJA_DATABASE_PASSWORD:?}
      POSTGRES_USER: vikunja
    volumes:
      - /var/app/vikunja/postgres-data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h localhost -U $$POSTGRES_USER"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 60s

2.3. Start the Services

Start the services in the background:

sudo docker compose up -d

Now the app is available at http://localhost:3456 or <your_pub_ip>:3456. (Don’t forget to open the port of the server in the firewall.)

3. Setup SSL Certificates

This part is same as the Self-Host Maybe Finance Web App - 3. Setup SSL Certificates section.

4. Disable Default nginx Site

This part is optional. This part is also same as the Self-Host Maybe Finance Web App - 4. Disable default Nginx site section.

5. Disable New Registration

At the moment, the self-hosted Vikunja instance allows anyone to register. If you want to disable new registration, you can set the VIKUNJA_SERVICE_ENABLEREGISTRATION environment variable to false in compose.yml.

For example:

services:
  vikunja:
    ...
    environment:
      ...
      VIKUNJA_SERVICE_ENABLEREGISTRATION: false
    ...

When new registration is disabled, the login page will not display the registration link.

6. Update for New Version

To update the Vikunja service to the latest version, you can pull the latest image and restart the service:

cd ~/app/todolist
sudo docker compose stop
sudo docker compose pull
sudo docker compose up -d

References

1. Vikunja: The open-source, self-hostable to-do app
2. vikunja/vikunja: The to-do app to organize your life. Public API Roadmap here: - vikunja - Gitea
3. Vikunja: Installing
4. Vikunja: Full docker example
5. Vikunja: Configuration options
6. Self-Host Maybe Finance Web App - Lingkang’s Blog