Use this file to discover all available pages before exploring further.
Tymeslot ships as a single Docker image with PostgreSQL embedded — there’s nothing else to install or wire up. One docker run command pulls the image, starts the database, runs migrations, and brings up the Phoenix web server. You can be taking bookings in under five minutes on any machine that has Docker installed.
A domain name is optional for local testing but required for a production deployment with SSL. For reverse proxy setup (Nginx, Caddy, Traefik), see the Reverse Proxy Setup guide.
The fastest way to get started. Docker pulls the published image from Docker Hub automatically.
Keep tymeslot_pg as a named volume. Swapping it for a host path (e.g. ./pgdata:/var/lib/postgresql/data) can break first-run initialisation on Docker Desktop, rootless Docker, userns-remap, or SELinux-enforcing hosts because the mount arrives with an ownership the container can’t change. If you need the database on a specific host path, use an external PostgreSQL instance instead.
Email defaults to silent discard. Without email configuration, EMAIL_ADAPTER defaults to test, which drops every message — password resets, booking confirmations, and reminders all vanish with no error. Configure SMTP or Postmark before going live. See the Email Configuration guide.
Run the following command to start Tymeslot with SMTP email configured:
Wait 30–60 seconds for PostgreSQL to initialise, then open http://localhost:4000.To pin a specific version instead of latest, replace the tag with a release number — e.g. luka1thb/tymeslot:1.2.0. The full list of published tags is on Docker Hub.
The embedded PostgreSQL listens only on localhost inside the container and is never exposed externally. If you omit POSTGRES_PASSWORD it defaults to tymeslot, which is fine for the embedded database. Set a strong password only when pointing Tymeslot at an external database via DATABASE_HOST.
Clone the repository, configure your .env file, then build and run with Docker Compose. Use this path when you want to pin your own image or run a custom fork.
Copy the example environment file and generate the required secrets:
cp .env.example .env
Generate secrets for the required variables:
# For SECRET_KEY_BASE (must be 64+ characters)openssl rand -base64 64 | tr -d '\n'# For POSTGRES_PASSWORDopenssl rand -base64 32 | tr -d '\n'
Open .env and fill in the required values:
# REQUIRED: Must be at least 64 charactersSECRET_KEY_BASE=<paste_generated_secret># REQUIRED: Your domain (or "localhost" for testing)PHX_HOST=localhost# REQUIRED: Database credentialsPOSTGRES_DB=tymeslotPOSTGRES_USER=tymeslotPOSTGRES_PASSWORD=<paste_generated_password># OPTIONAL: Port (defaults to 4000)PORT=4000
Email defaults to silent discard. Without email configuration, EMAIL_ADAPTER defaults to test, which drops every message. Add SMTP or Postmark variables to .env before going live. See the Email Configuration guide.
3
Build and start the container
docker compose up -d --build
Docker Compose reads your .env, builds the image, and starts the container with the tymeslot_data and tymeslot_pg volumes.
4
Wait for initialisation
Startup takes 30–60 seconds on first run (PostgreSQL initialisation + database migrations). Watch progress with:
docker logs -f tymeslot
Look for the line: Running TymeslotWeb.Endpoint — that’s your signal that the server is ready.
5
Open the app
Visit http://localhost:4000 (or whatever PORT you set). Create your first account — it will be automatically promoted to admin.
The first user to register on a fresh install is automatically promoted to admin. To promote additional users — or recover access if no admin exists — run the release helper from inside the container:
The container needs 30–60 seconds to initialise on first run. Watch the logs and wait for Running TymeslotWeb.Endpoint:
docker logs -f tymeslot
If you see that line but the browser still can’t connect, check that you’re using the right port (default 4000) and that no firewall rule is blocking it.
Database issues
Check that PostgreSQL is running inside the container:
To reset the database entirely (destroys all data — stop the container first, as the volume can’t be removed while in use):
docker rm -f tymeslotdocker volume rm tymeslot_pg
initdb: could not change permissions — Operation not permitted
This error appears on first start when the PostgreSQL volume is bind-mounted at /var/lib/postgresql/data with ownership the container can’t change. It’s common on Docker Desktop, rootless Docker, and SELinux-enforcing hosts.Fixes in order of preference:
Use the named volume from the quick-start (-v tymeslot_pg:/var/lib/postgresql/data). Named volumes live inside Docker’s own storage and are immune to host filesystem ownership quirks.
If you need the data on a specific host path, run PostgreSQL externally and point Tymeslot at it with DATABASE_HOST.
If a previous first-run attempt crashed, remove the partially-initialised volume before retrying: docker volume rm tymeslot_pg.
Port already in use
Find what’s occupying port 4000:
sudo lsof -i :4000
Either stop the conflicting service, or change the port Tymeslot listens on:
# In your .env file or -e flag:PORT=8080
Then update your docker run command accordingly: -p 8080:8080.
Integration credentials (calendar tokens, CalDAV passwords, video API keys) are encrypted at rest. By default the encryption key is derived from SECRET_KEY_BASE, which means rotating your session secret would make stored credentials unreadable. Setting a dedicated DATA_ENCRYPTION_KEY decouples the two so you can rotate SECRET_KEY_BASE freely.
# Add to your .env (generate once, keep stable forever)DATA_ENCRYPTION_KEY=$(openssl rand -base64 48 | tr -d '\n')
See Data-at-Rest Encryption for full details, including how to migrate existing credentials onto the new key.
