Quick start

Choose Cloudflare or Docker and follow this guide to deploy Calends and sign in for the first time.

Calends runs in two ways with the same features: on Cloudflare Workers or with Docker on your own machine. You can also paste the prompt below into an AI agent with terminal access and let it do the work.

Cloudflare

One-click deploy: use the Deploy to Cloudflare button in the GitHub README, or open deploy.workers.cloudflare.com. Afterwards, add a secret named SETUP_TOKEN in the Worker’s settings — without it you can’t set a password.

From the command line:

1. Clone the repository and install dependencies:

   git clone https://github.com/imetn/calends && cd calends
   npm ci

2. Sign in to Cloudflare:

   npx wrangler login

3. Set the setup token. Use any long random string; you’ll type it once when setting your password:

   npx wrangler secret put SETUP_TOKEN

4. Deploy. This builds the front end, creates the D1 database automatically, deploys the Worker and runs the database migrations:

   npm run deploy

5. Open https://<your-worker>.workers.dev/admin, enter the setup token and choose your password.

For email reminders, the cron trigger and custom domains, see Cloudflare Workers + D1.

Docker

docker run -d --name calends -p 8787:8787 -v calends-data:/data ghcr.io/imetn/calends:latest
docker logs calends   # prints the one-time setup token on first run

Open http://localhost:8787/admin, enter the setup token from the logs and choose your password. Data lives in the calends-data volume as SQLite.

Caution

On the public internet, put it behind a reverse proxy such as Caddy, Nginx or Traefik for HTTPS (passkeys require HTTPS), and set the environment variable TRUST_PROXY=1.

For compose, the data directory and scheduled jobs, see Docker.

Let an AI agent do it

Paste this into Claude Code, Codex, Cursor or any coding agent with terminal access:

Deploy Calends (https://github.com/imetn/calends), a self-hosted subscription ledger, for me.
1. Ask me whether to deploy to Cloudflare Workers (free) or Docker on this machine/server.
2. Cloudflare: clone the repo, run `npm ci`, make sure `npx wrangler whoami` works (run `npx wrangler login` if not),
   generate a random SETUP_TOKEN and set it with `npx wrangler secret put SETUP_TOKEN`, then `npm run deploy`.
   If I want a custom domain, add it under "routes" in wrangler.jsonc as a custom_domain before deploying.
3. Docker: run the official image ghcr.io/imetn/calends with a named volume for /data and port 8787,
   then read the setup token from the container logs. Offer to put it behind HTTPS with Caddy.
4. Finally give me the /admin URL and the setup token, and remind me to add a passkey and connect my AI assistant
   on the AI access page (MCP).

After deploying

1. At /admin, enter the setup token and choose a password of at least 8 characters. See First-time setup.
2. Under Settings → General, pick your base currency, time zone and language.
3. Under Settings → Security, add a passkey so you can sign in with Face ID, Touch ID or your device passcode.
4. Add your first subscription: press N, or paste a receipt into the Assistant.
5. To get reminders, add at least one channel under Notification channels in Settings.

Note

The site root / is the read-only public page, which is off by default; the app itself lives at /admin. See Public page.