Deploy Vikunja | (Just Updated) Self-Hosted To-Do and Project Manager, REST API, Sign-Up Closed, Admin Preset

Vikunja to-do and project API, sign-up closed, admin preset, data kept

Deploy Vikunja | (Just Updated) Self-Hosted To-Do and Project Manager, REST API, Sign-Up Closed, Admin Preset

Just deployed

/db

Deploy and Host Vikunja on Railway

Built for an LLM agent to deploy and use. The deploy form has no fields to fill: the session-signing secret and the administrator's credential are generated, the administrator account admin is created at first boot, public registration is closed, and the database and uploaded files sit on a volume. Vikunja is the open-source, self-hosted to-do and project manager with lists, Kanban, Gantt and table views, and a REST API.

About Hosting Vikunja

This template runs one service, vikunja: the upstream Vikunja 2.8.0 image (pinned by digest) through a thin wrapper, with a volume at /db holding the SQLite database and every uploaded attachment. The volume survives redeploys, so projects, tasks, users and files persist. The service listens on Railway's injected PORT, and the healthcheck is GET /api/v1/info.

What the wrapper fixes. Upstream ships with open registration and creates no account, so a fresh public deploy either lets any visitor register or needs a person to register first. The wrapper turns registration off and creates the administrator from the generated credential before the server listens, so the first request already meets a closed instance with a known login. The upstream image is a static binary on an empty filesystem with no shell, so the wrapper also copies it onto a minimal Alpine base to run a boot script, fix volume ownership and drop privileges.

Using it. Sign in at the public URL as admin with the value of VIKUNJA_ADMIN_PASSWORD, then create further users from the administrator's side or through the API. The administrator's address is the placeholder admin@example.com; to use your own, add a VIKUNJA_ADMIN_EMAIL variable before the first deploy (and VIKUNJA_ADMIN_USERNAME to rename the account). Outgoing email is not configured; add the upstream VIKUNJA_MAILER_* variables described in the Vikunja documentation to enable reminders and password resets.

Agent contract

  • Public URL: https://RAILWAY_PUBLIC_DOMAIN (the generated domain of the vikunja service)
  • Private URL: http://vikunja.railway.internal:8080
  • Credentials: the variable VIKUNJA_ADMIN_PASSWORD on the vikunja service, for the user admin; the variable VIKUNJA_SERVICE_SECRET signs sessions and is not a login
  • Auth: POST /api/v1/login with {"username":"admin","password":"..."} returns a JSON token; send it as Authorization: Bearer TOKEN on every other call. A request with no token or a wrong token answers 401, and a wrong login answers 403. Public sign-up is closed.
  • Health: GET /api/v1/info returns 200
#!/bin/sh
# needs: RAILWAY_PUBLIC_DOMAIN, VIKUNJA_ADMIN_PASSWORD (variables of the vikunja service; the user name is admin); also curl, sed. Creates one throwaway project and deletes it.
R="https://$RAILWAY_PUBLIC_DOMAIN"; J="Content-Type: application/json"
n=0; until [ "$(curl -s -o /dev/null -w '%{http_code}' "$R/api/v1/info")" = 200 ]; do n=$((n+1)); [ "$n" -le 60 ] || break; sleep 5; done
curl -s -o /dev/null -w "health: %{http_code}\n" "$R/api/v1/info"
# sign in as the administrator and take the API token
TOKEN=$(curl -s -H "$J" -d "{\"username\":\"admin\",\"password\":\"$VIKUNJA_ADMIN_PASSWORD\"}" "$R/api/v1/login" | sed -n 's/.*"token":"\([^"]*\)".*/\1/p')
if [ -n "$TOKEN" ]; then echo "login: ok"; else echo "login: FAILED"; fi
# write with the token: create a project, read it back, delete it
ID=$(curl -s -X PUT -H "$J" -H "Authorization: Bearer $TOKEN" -d '{"title":"agent-contract-check"}' "$R/api/v1/projects" | sed -n 's/^{"id":\([0-9]*\),.*/\1/p')
if [ -n "$ID" ]; then echo "write project: created"; else echo "write project: FAILED"; fi
curl -s -o /dev/null -w "read project: %{http_code}\n" -H "Authorization: Bearer $TOKEN" "$R/api/v1/projects/$ID"
curl -s -o /dev/null -w "delete project: %{http_code}\n" -X DELETE -H "Authorization: Bearer $TOKEN" "$R/api/v1/projects/$ID"
# refusals: no token, wrong token, wrong login, public sign-up
curl -s -o /dev/null -w "write without key: %{http_code}\n" -X PUT -H "$J" -d '{"title":"x"}' "$R/api/v1/projects"
curl -s -o /dev/null -w "write wrong key: %{http_code}\n" -X PUT -H "$J" -H "Authorization: Bearer not-a-token" -d '{"title":"x"}' "$R/api/v1/projects"
curl -s -o /dev/null -w "login wrong secret: %{http_code}\n" -H "$J" -d '{"username":"admin","password":"not-the-secret-0000"}' "$R/api/v1/login"
curl -s -o /dev/null -w "public signup: %{http_code}\n" -H "$J" -d '{"username":"intruder","email":"intruder@example.com","password":"intruder-0000-0000"}' "$R/api/v1/register"

Expected output against a fresh deploy (measured on a Railway deploy of this template):

health: 200
login: ok
write project: created
read project: 200
delete project: 200
write without key: 401
write wrong key: 401
login wrong secret: 403
public signup: 404

The refusals are the contract: write without key: 401, write wrong key: 401, login wrong secret: 403 and public signup: 404 (the registration route does not exist while registration is closed). The first five lines show the administrator can sign in and use the API.

Why Deploy Vikunja on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Vikunja on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

  • Agent-ready - no deployer fields, a contract block, and one script that proves the instance is healthy, the administrator can sign in and write, and unauthenticated writes and sign-ups are refused.
  • Administrator from variables - the account is created at boot from a generated credential, with no registration step.
  • Sign-up closed - nobody else can register on the public URL.
  • Data survives redeploys - the SQLite database and uploads live on a volume.
  • Pinned - the upstream image is pinned by digest and the wrapper by tag and digest.

Common Use Cases

  • Self-hosted to-do and task manager - lists, labels, due dates, reminders and sharing in a database you control.
  • Project management with Kanban, Gantt and table views - an open-source alternative to hosted task boards.
  • Task backend for an AI agent - give an automation a REST API to read and write projects and tasks.
  • Team or family planner - shared projects with per-user permissions.

Dependencies for Vikunja Hosting

  • The vikunja service with its volume, created by the template. A custom domain is optional; the application URL follows the Railway domain.

Deployment Dependencies


Template Content

More templates in this category

View Template
Rocky Linux
Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀

codestorm
51
View Template
Foundry Virtual Tabletop
Self-hosted virtual tabletop for role-playing games (license required)

Lucas
71
View Template
NEW
Double Commander in your browser
The Double Commander file manager in the cloud, from any device

Nermin Sabanovic
0