Get CheckTick running on your own infrastructure in minutes using pre-built Docker images.

Overview

CheckTick can be self-hosted using Docker, similar to platforms like Discourse. You don't need to clone the repository or build anything - just pull the pre-built image and configure your deployment.

Self-hosted deployments automatically include all Enterprise tier features:

• Custom branding (logos, themes, fonts)
• No survey limits
• Full collaboration features
• SSO/OIDC integration support

Branding Configuration: Superusers can configure platform branding via:

• Web UI at /branding/ (requires superuser account)
• CLI command: python manage.py configure_branding
• Django admin at /admin/core/sitebranding/

See Configuration Guide for full setup details.

Prerequisites

CheckTick requires the following infrastructure. Understand what you need before you start:

⚠️ vault-data and snomed-data must be separate volumes. Vault uses Raft storage and cannot share its volume with other data.

Host system requirements:

• Docker 24.0+ and Docker Compose 2.0+
• 4 GB RAM (8 GB recommended if running the SNOMED seeding process on the same host)
• Domain name with TLS certificate (required for production; optional for local dev)

Environment Variables

All configuration is done via environment variables. Start from the provided template:

# Download the template
curl -O https://raw.githubusercontent.com/eatyourpeas/checktick/main/.env.example
mv .env.example .env

.env.example contains every supported variable with inline comments. Work through each section and fill in your values. Then copy those values into your hosting provider's secrets/credentials store — never commit a populated .env to version control.

Required variables — the app will not start without these:

Optional but recommended:

See Configuration Guide for the full reference including data governance, compliance roles, and advanced options.

Quick Start

1. Download Deployment Files

# Create a directory for your deployment
mkdir checktick-app && cd checktick-app

# Download the compose file
curl -O https://raw.githubusercontent.com/eatyourpeas/checktick/main/docker-compose.registry.yml

# Download environment template
curl -O https://raw.githubusercontent.com/eatyourpeas/checktick/main/.env.example
mv .env.example .env

2. Configure Environment

Copy .env.example to .env and fill in your values (or use the download step above):

# Generate a secure secret key
openssl rand -base64 50

# Edit configuration
nano .env

At minimum, set:

# Security
SECRET_KEY=your-generated-secret-key
ALLOWED_HOSTS=yourdomain.com,localhost
CSRF_TRUSTED_ORIGINS=https://yourdomain.com

# Database
DATABASE_URL=postgres://checktick:password@db:5432/checktick
SITE_URL=https://yourdomain.com

# Email
DEFAULT_FROM_EMAIL=no-reply@yourdomain.com
EMAIL_HOST=smtp.eu.mailgun.org
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_HOST_USER=postmaster@mg.yourdomain.com
EMAIL_HOST_PASSWORD=your-smtp-password

# External Datasets (free key from https://api.rcpch.ac.uk)
EXTERNAL_DATASET_API_URL=https://api.rcpch.ac.uk
EXTERNAL_DATASET_API_KEY=your-rcpch-api-key

# Vault (generated during vault initialisation — see vault.md)
VAULT_ADDR=https://vault.yourdomain.com:8200
VAULT_ROLE_ID=your-role-id
VAULT_SECRET_ID=your-secret-id

# SNOMED CT (optional — free key from https://isd.digital.nhs.uk/trud)
TRUD_API_KEY=your-trud-api-key
SNOMED_DB_PATH=/app/data/snomed.db

Note: CheckTick will start without email configured, but users cannot be invited or reset passwords. Vault and email are essential for a working production system.

3. Start CheckTick

# Pull the latest image and start services
docker compose -f docker-compose.registry.yml up -d

# Check status
docker compose ps

# View logs
docker compose logs -f web
````

### 4. Create Superuser Account

**Important:** Superuser accounts have full administrative access including:

- Access to Django admin interface at `/admin/`
- Ability to configure platform branding at `/branding/`
- User management and system configuration
- Access to all surveys and data

```bash
# Create your first superuser account
docker compose exec web python manage.py createsuperuser

# Follow the prompts:
# - Username: (your admin username)
# - Email: (your admin email)
# - Password: (strong password)

Creating Additional Superusers:

After initial setup, you can create additional superuser accounts in two ways:

1. Via Django Admin (Recommended):
2. Log in to /admin/ with your superuser account
3. Navigate to "Users" under "Authentication and Authorization"
4. Select a user and check "Superuser status"

5. Or create a new user and grant superuser status

6. Via Command Line:

```bash # Create a new superuser docker compose exec web python manage.py createsuperuser

# Or promote an existing user to superuser docker compose exec web python manage.py shell

from django.contrib.auth import get_user_model User = get_user_model() user = User.objects.get(username='existing_username') user.is_superuser = True user.is_staff = True user.save() exit() ```

Regular User Registration:

Regular users (non-superusers) can sign up through the web interface at /signup/ once your instance is running. They don't need command-line access.

Demo Accounts for Testing (Development/Staging Only):

For testing different account tiers without going through billing, use the demo accounts command:

# Create all demo accounts
docker compose exec web python manage.py create_demo_accounts

# Create only a specific tier
docker compose exec web python manage.py create_demo_accounts --tier team_small

# Reset and recreate all demo accounts
docker compose exec web python manage.py create_demo_accounts --reset

This creates 7 demo accounts with different tiers:

• demo-free@example.com - Free tier
• demo-pro@example.com - PRO tier with encryption
• demo-team-small@example.com - Team (5 members) with pre-created team
• demo-team-medium@example.com - Team (10 members) with pre-created team
• demo-team-large@example.com - Team (20 members) with pre-created team
• demo-org@example.com - Organization tier with pre-created organization
• demo-enterprise@example.com - Enterprise tier with custom branding

Password for all accounts: demo123!pass

All accounts require 2FA setup on first login (even though billing is bypassed).

⚠️ SECURITY WARNING: This command is for development and staging only. It is blocked in production by checking the ENVIRONMENT variable. Set ENVIRONMENT=production before going live to prevent creation of accounts with known passwords. Always run with --reset before going live to delete all demo accounts.

5. Access Your Instance

Visit http://localhost:8000 (or your domain) and log in with your admin credentials.

Next Steps

• Scheduled Tasks - REQUIRED for GDPR compliance and maintenance
• Production Setup - SSL, nginx, security hardening
• Database Options - External managed databases (AWS RDS, Azure, etc.)
• Configuration Guide - Branding, authentication, email providers
• Theming & UI Customization - Theme presets, custom CSS, and daisyUI configuration
• Backup & Restore - Database backups and disaster recovery

Before Going Live (Production Checklist)

When preparing to accept real users and go into production:

1. Set environment variable:

bash ENVIRONMENT=production

This disables demo account creation to prevent security vulnerabilities.

1. Delete all demo accounts:

bash docker compose exec web python manage.py create_demo_accounts --reset

This removes all demo-*@example.com accounts with known passwords.

1. Review security settings:
2. Ensure DEBUG=False in production
3. Verify SECRET_KEY is secure and not shared
4. Check ALLOWED_HOSTS is properly configured

5. Enable SSL/TLS (see Production Setup)

6. Test authentication:

7. Verify 2FA is working
8. Test password reset emails
9. Confirm email notifications are sending

Troubleshooting

Container won't start

# Check logs for errors
docker compose logs web

# Common issues:
# - Missing required environment variables
# - Database connection failed
# - Port 8000 already in use

Can't access the site

1. Check firewall allows port 8000
2. Verify ALLOWED_HOSTS includes your domain/IP
3. Check container is running: docker compose ps

Database errors

# Ensure database is healthy
docker compose ps db

# Check database logs
docker compose logs db

# Reset database (WARNING: destroys all data)
docker compose down -v
docker compose up -d

Email not sending

1. Verify email credentials in .env
2. For Gmail, use App Passwords
3. Check email service allows SMTP access
4. Test with: docker compose exec web python manage.py sendtestemail your@email.com

Updating CheckTick

# Pull latest image
docker compose pull

# Restart with new image
docker compose up -d

# Migrations run automatically on startup

Getting Help

• Documentation - Full guides
• GitHub Issues - Report bugs or problems
• GitHub Discussions - Ask questions

Architecture

Your deployment includes:

• Web Application - Django application serving CheckTick
• PostgreSQL Database - Data storage with persistent volume
• Media Volume - Uploaded files and user content

All data persists in Docker volumes even when containers are stopped or upgraded.