oxisoft/oxitick repository overview

⁠OxiTick Server

Self-hosted sync server for OxiTick⁠ — a private, offline-first app for personal or collaborative to-do lists and notes. The app works fully offline; point it at this server to sync your data across devices and share lists with the people you choose. Your data never leaves infrastructure you control: no third-party cloud, no tracking, no ads.

Images: linux/amd64 and linux/arm64 (Raspberry Pi 4/5, Apple Silicon hosts, ARM VPS).

⁠Quick start

docker run -d --name oxitick -p 15773:15773 -v ./data:/app/data oxisoft/oxitick:latest

That's it — no configuration required. Auth secrets are generated automatically on first start and stored in the data volume. Or with compose:

# docker-compose.yml
services:
  oxitick:
    image: oxisoft/oxitick:latest
    ports:
      - "15773:15773"
    volumes:
      - ./data:/app/data
    environment:
      # Recommended: create the admin account at first start (see below)
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=change-me-min-8-chars
    restart: unless-stopped

docker compose up -d

Then open http://your-host:15773/admin, log in, and create app user accounts under Users. In the OxiTick app: Settings → Sync Settings → enter the server URL and the user credentials.

⁠First-run admin account

Two ways to create the admin (for the /admin panel):

1. Environment bootstrap (recommended): set ADMIN_USERNAME and ADMIN_PASSWORD — the account is created before the server accepts its first request, so there is no window where an unauthenticated visitor could claim /admin/setup. Once an admin exists, these variables are ignored (they never overwrite).
2. Interactive setup: without those variables, the first visit to /admin redirects to a one-time setup page. Fine for trusted networks; on anything internet-reachable, prefer option 1.

App user accounts are admin-created only — there is no public registration endpoint.

⁠Environment variables

⁠Volumes

⁠Storing data in a specific host directory

To keep the data at a fixed path on the host (easy to find, easy to back up), bind-mount an absolute directory instead of the relative ./data:

# docker-compose.yml — data lives in /srv/oxitick/data on the host
services:
  oxitick:
    image: oxisoft/oxitick:latest
    ports:
      - "15773:15773"
    volumes:
      - /srv/oxitick/data:/app/data
    environment:
      - ADMIN_USERNAME=admin
      - ADMIN_PASSWORD=change-me-min-8-chars
    restart: unless-stopped

The container runs as a non-root user (UID 1000), so the host directory must be writable by it:

sudo mkdir -p /srv/oxitick/data
sudo chown -R 1000:1000 /srv/oxitick/data

Backing up is then just copying /srv/oxitick/data (stop the container first, or use SQLite's .backup, so the database isn't copied mid-write).

Alternatively, a named volume (- oxitick_data:/app/data plus a top-level volumes: {oxitick_data:}) lets Docker manage the location and permissions for you — best when you don't care where the files physically live.

⁠Health & version

GET /health → {"status":"ok","service":"oxitick","version":"v1.2.3"} — the running version is also shown on the admin dashboard.

⁠HTTPS

The container serves plain HTTP; run it behind your reverse proxy of choice. Self-contained automatic HTTPS with a DOMAIN variable works well with a Caddy sidecar:

services:
  oxitick:
    image: oxisoft/oxitick:latest
    volumes: [ "./data:/app/data" ]
    restart: unless-stopped
  caddy:
    image: caddy:2
    ports: [ "80:80", "443:443" ]
    environment: [ "DOMAIN=${DOMAIN}" ]
    volumes:
      - caddy_data:/data
      - ./Caddyfile:/etc/caddy/Caddyfile
    restart: unless-stopped
volumes:
  caddy_data:

# Caddyfile
{$DOMAIN} {
    reverse_proxy oxitick:15773
}

DNS for DOMAIN must point at the host and ports 80/443 must be reachable; certificates are obtained and renewed automatically.

⁠Tags

• latest — most recent release
• X.Y.Z — exact release (recommended for production)
• X.Y — latest patch of a minor line

Made by OxiSoft⁠ · App website: oxitick.com⁠