JavaScript Disabled This app requires JavaScript to function. Please enable it in your browser settings. Refresh Page

Connection Lost

Attempting to reconnect

Back to Overview

Upgrading Tymeslot

Keep your Tymeslot instance up to date. Database migrations run automatically on startup — upgrades are a single command.

Luka Breitig

Technical Product Builder & AI Developer

📋 Before You Begin

Requirements

A running Tymeslot instance (Docker-based)
SSH access to the server
Root or sudo privileges

Expect

Under 30 seconds of downtime for a typical container restart
Migrations run automatically on startup — no manual steps
Brief downtime is unavoidable; notify users for major upgrades

Outcome: By the end of this guide, your instance will be running the latest Tymeslot version with all database migrations applied and verified.

🔢 Understanding Version Numbers

Tymeslot follows semantic versioning (MAJOR.MINOR.PATCH). The version number tells you how much care the upgrade requires:

PATCH (x.x.N)

Always safe to apply immediately. Bug fixes and security patches only. No schema changes, no config changes required.

MINOR (x.N.0)

May include database migrations. Read the release notes on GitHub before upgrading. Back up first — always.

MAJOR (N.0.0)

May require changes to environment variables or configuration files. Read the migration guide for the specific release carefully before upgrading.

🛡️ Before You Upgrade

Complete these two steps before touching the running instance:

1. Note the current version

Inspect the running container image tag to find the current version:

docker-compose images tymeslot

Note this version down. You will need the exact tag if a rollback is required.

2. Back up the database

Run this one-liner to create a timestamped backup before every upgrade:

docker-compose exec -T postgres pg_dump -U tymeslot tymeslot \
  > backup-before-upgrade-$(date +%Y%m%d-%H%M%S).sql

You should see the file created in the current directory with no error output. Confirm it is non-empty: ls -lh backup-before-upgrade-*.sql

1 Pull the Latest Image

Fetch the new image without stopping the running application:

docker-compose pull tymeslot

You should see Docker downloading image layers and printing Status: Downloaded newer image for the Tymeslot image. If it prints Image is up to date, you are already on the latest version.

If you are building Tymeslot from source instead of using a pre-built image:

git pull origin main

2 Apply the Update

Stop the running containers and start them fresh with the new image:

# Pre-built image
docker-compose down
docker-compose up -d

# Building from source — rebuild the image first
docker-compose down
docker-compose up -d --build

Watch the startup logs

Tail the logs to confirm a clean startup:

docker-compose logs -f tymeslot

A successful startup will print lines like Running X migrations (if any were pending) followed by Access TymeslotWeb.Endpoint at https://…. Press Ctrl-C to stop following once you see the endpoint message.

Migrations Run Automatically

You do not need to run migrations manually. Tymeslot runs all pending Ecto migrations at startup before accepting traffic. Look for Running X migrations in the startup logs. If you see Running 0 migrations, this release had no schema changes.

If the container fails to start after upgrading

A failed migration is the most common cause. Check the logs for the specific error:

docker-compose logs tymeslot | grep -A 5 "ERROR\|migration"

If you see a migration error, restore your pre-upgrade backup (see the Rollback section below) and open a GitHub issue with the full log output.

3 Confirm the Application Is Healthy

Check container status and confirm the application is responding:

# Check container status — all services should show 'Up'
docker-compose ps

# Confirm the health endpoint responds with 200
curl -s -o /dev/null -w "%{http_code}" https://tymeslot.yourdomain.com/healthcheck

The health endpoint returns 200 only when the application is running and the database connection is live. Any other status code indicates a problem — check the logs.

↩️ Rolling Back to a Previous Version

If the new version is causing problems, follow these steps to restore the previous state:

1. Stop the application

docker-compose stop tymeslot

2. Restore the pre-upgrade database backup

docker-compose exec -T postgres psql -U tymeslot tymeslot \
  < backup-before-upgrade-20260301-140000.sql

3. Pin the previous image tag in docker-compose.yml

Edit the image line for the tymeslot service to use the version you noted earlier:

# Change this:
image: ghcr.io/tymeslot/tymeslot:latest

# To the pinned previous version, e.g.:
image: ghcr.io/tymeslot/tymeslot:v1.2.3

4. Start the previous version

docker-compose up -d tymeslot

Rollback After Migrations May Leave the Schema Inconsistent

If the new version ran database migrations before failing, rolling back the application code without restoring the backup will leave the schema in a state the old code does not understand. Always restore the database backup as part of a rollback, not just the image tag.

❓ Frequently Asked Questions

Do I need to run database migrations manually?

No. Tymeslot runs all pending Ecto migrations automatically at startup, before the application begins accepting traffic. You do not need to exec into the container or run any migration commands yourself. Watch the startup logs for Running X migrations to confirm they applied, or Running 0 migrations if this release had no schema changes.

What if the new image fails to start after upgrading?

First, check the logs for the specific error — a failed migration is the most common cause:

docker-compose logs tymeslot | grep -E "ERROR|migration"

If the problem is not immediately fixable, roll back by restoring the pre-upgrade backup and pinning the previous image tag in docker-compose.yml — the exact steps are in the Rollback section above. Always restore the database backup alongside reverting the image tag; reverting the image without restoring the database will leave the schema in a state the old code does not understand.

Can I skip versions when upgrading?

Generally yes — Tymeslot migrations are cumulative and designed to be applied in sequence regardless of how many were skipped. However, major version bumps (N.0.0) may require changes to environment variables or configuration files that are not handled automatically. Always read the release notes on GitHub before skipping multiple minor or major versions, and back up before every upgrade regardless of the gap.

Will upgrading cause downtime?

Briefly, yes. Stopping the container and starting the new one typically takes under 30 seconds. During that window the application is unreachable. For most self-hosted deployments this is acceptable — schedule upgrades during off-peak hours and notify users ahead of time for major releases. Zero-downtime deployments require a load balancer and a rolling deploy strategy, which is beyond the scope of a single-container setup.

I pulled the latest image but docker-compose says 'Image is up to date' — am I already on the newest version?

Yes, if you are tracking the latest tag. Docker compares the image digest against what it has locally — if they match, nothing is downloaded. To confirm which version is actually running, check the footer of the Tymeslot admin interface, or inspect the image metadata:

docker-compose images tymeslot

If you pin a specific version tag (e.g. v1.2.3) in docker-compose.yml, update the tag to the new version before running docker-compose pull.

Verify Your Setup

Confirm each of the following before considering the upgrade complete:

Health endpoint returns 200. The healthcheck URL responds with HTTP status 200 when the app and database are up.
Login succeeds. Sign in with an existing account to confirm the user table and session handling are intact.
Startup logs show 0 pending migrations. Run docker-compose logs tymeslot | grep migration — you should see Running 0 migrations confirming all migrations were applied on the first boot.
Pre-upgrade backup is stored safely. Copy backup-before-upgrade-*.sql to off-site storage before deleting it from the server.

🔗 Related Articles

Backup & Restore

Back up and restore your Tymeslot data. All scheduling data lives in PostgreSQL — a simple pg_dump is all you need.

Docker Self-Hosting

Deploy Tymeslot using Docker and Docker Compose. Perfect for VPS hosting, home servers, or any environment with Docker support.

Cloudron Deployment

One-click installation on Cloudron. Automated backups, SSL certificates, and updates handled automatically.