Docker Self-Hosting

📋 Prerequisites

• Docker: Installed on your server (Docker Engine 20.10+ recommended). Docker Compose is optional.
• Domain Name: A domain or subdomain pointing to your server (e.g., tymeslot.yourdomain.com). Optional for local testing.
• Server Resources: Minimum 1GB RAM (2GB recommended), 1 CPU core, 10GB storage
• SSL Certificate: Use a reverse proxy like Nginx or Caddy with Let's Encrypt for automatic SSL

📦 How it runs

Tymeslot runs as one container: the Phoenix application and its PostgreSQL database live side by side, with all state on two named volumes — tymeslot_data (uploads and timezone data) and tymeslot_pg (the database). There is no separate database container to manage.

Prefer a managed or external PostgreSQL? Set DATABASE_URL to the connection string your provider gives you, or use the discrete DATABASE_HOST variables described in the Environment Variable Reference — the embedded database is then skipped automatically. Managed databases usually require TLS, so add DATABASE_SSL=true.

For an external database there is a second image tag, luka1thb/tymeslot:slim — the same application with no PostgreSQL server inside it, around 170 MB smaller. It requires an external database and tells you so if none is configured.

To run the database as its own container instead, the repository ships a ready-made Compose file that pairs the slim image with a postgres:17-alpine sidecar, waiting on its health check before starting. Backups then become a plain pg_dump against a container that does one thing:

cp .env.example .env
# fill in SECRET_KEY_BASE, PHX_HOST and POSTGRES_PASSWORD
docker compose -f docker-compose.with-postgres.yml up -d

1 Run the prebuilt image (fastest)

Pull and run the published image directly. This is the quickest way to get a working instance:

docker run -d \
  --name tymeslot \
  -p 4000:4000 \
  -e SECRET_KEY_BASE="$(openssl rand -base64 64 | tr -d '\n')" \
  -e PHX_HOST=tymeslot.yourdomain.com \
  -v tymeslot_data:/app/data \
  -v tymeslot_pg:/var/lib/postgresql/data \
  luka1thb/tymeslot:latest

For a pinned release, replace :latest with a version tag (e.g. luka1thb/tymeslot:1.0.5).

2 Or build from source with Docker Compose

If you'd rather build the image yourself, clone the repository and use the docker-compose.build.yml and .env.example that ship in the repo — you do not need to write your own Compose file. (The default docker-compose.yml pulls the published image instead of building one, which is option 1 above.)

# Clone and enter the repository\ngit clone https://github.com/Tymeslot/tymeslot.git\ncd tymeslot\n\n# Create your environment file\ncp .env.example .env\n\n# Generate the required secrets and paste them into .env\nopenssl rand -base64 64 | tr -d '\\n'   # SECRET_KEY_BASE\nopenssl rand -base64 32 | tr -d '\\n'   # POSTGRES_PASSWORD (only needed for an external DB)\n\n# Build and start (Compose reads .env automatically)\ndocker compose -f docker-compose.build.yml up -d --build

Watch the logs until the Phoenix server reports it is running:

docker compose logs -f tymeslot

3 Configure environment variables

Only three variables are required. Everything else has a sensible default — see the Environment Variable Reference for the full list.

# REQUIRED: signing secret (generate with: openssl rand -base64 64 | tr -d '\\n')\nSECRET_KEY_BASE=your_generated_secret_here\n\n# REQUIRED: the hostname you will serve Tymeslot on\nPHX_HOST=tymeslot.yourdomain.com\n\n# REQUIRED only for an EXTERNAL database (the embedded one defaults this internally)\nPOSTGRES_PASSWORD=your_secure_password_here\n\n# Optional: host port to publish (default 4000)\nPORT=4000

Email configuration

# Option 1: SMTP (recommended for most users)
EMAIL_ADAPTER=smtp
EMAIL_FROM_NAME="Your Company Name"
EMAIL_FROM_ADDRESS="hello@yourdomain.com"
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your_email@gmail.com
SMTP_PASSWORD=your_app_password

# Option 2: Postmark (recommended for high reliability)
# EMAIL_ADAPTER=postmark
# EMAIL_FROM_NAME="Your Company Name"
# EMAIL_FROM_ADDRESS="hello@yourdomain.com"
# POSTMARK_API_KEY=your_postmark_api_key

Step-by-step provider guides: SMTP and Postmark.

4 Set up SSL with a reverse proxy

For production use, terminate TLS at a reverse proxy in front of Tymeslot. Here's a minimal Caddy example (Caddy fetches and renews certificates automatically):

tymeslot.yourdomain.com {\n    reverse_proxy localhost:4000\n    encode gzip\n}

5 Access your instance

Open your browser and navigate to your domain:

Click "Sign Up" to create your first account. You'll be guided through the setup process where you can:

• Create your account and complete registration
• Connect your calendar (Google Calendar, CalDAV, Nextcloud)
• Configure video conferencing (Google Meet, Microsoft Teams, Zoom, MiroTalk P2P, or custom links)
• Set up your availability and create meeting types
• Customize your booking page theme

🔧 Maintenance & Updates

To update to the latest version (build-from-source install):

# Pull latest changes\ngit pull origin main\n\n# Rebuild and restart\ndocker compose -f docker-compose.build.yml down\ndocker compose -f docker-compose.build.yml up -d --build

Running the prebuilt image instead? Pull the new tag and recreate the container — your tymeslot_data and tymeslot_pg volumes carry your data across the upgrade. See the Upgrading guide.

To back up the embedded database:

docker exec -t tymeslot su - postgres -c 'pg_dump tymeslot' > backup.sql

Full backup and restore procedure (including the data volume): Backup & Restore .