Docker Self-Hosting
Deploy Tymeslot with Docker Compose on any VPS or home server. Includes reverse proxy setup, file upload volumes, and WebSocket configuration for LiveView.
Back to Overview
Upgrading Tymeslot
Keep your Docker instance of Tymeslot up to date. Database migrations run automatically on startup, so an upgrade is a backup, a pull and a restart.
Luka Breitig
Updated 2 October 2026
📋 Before You Begin
Requirements
- A running Tymeslot instance (Docker-based)
- SSH access to the server
-
Root or
sudoprivileges
Expect
- Under 30 seconds of downtime for a typical container restart
- Migrations that run automatically on startup, with no manual steps
- No way to avoid that downtime, so warn users before major upgrades
Outcome: By the end of this guide, your instance runs the latest Tymeslot version with every database migration applied and checked.
🔢 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)
Bug fixes and security patches, safe to apply promptly. Some include a small database migration, which runs automatically; none need configuration changes.
MINOR (x.N.0)
New features, often with database migrations. Read the release notes on GitHub before upgrading, and always back up first.
MAJOR (N.0.0)
May require changes to environment variables or configuration files. Read that release's notes carefully before upgrading.
📌 Notes for Specific Versions
Most releases need nothing beyond the steps below. A release that does extra work on its first start, or changes what it accepts, is listed here.
1.22.0: uploads no longer carry location or camera details
Avatars and theme backgrounds are now stored without the location, capture time and camera or phone details that photos and videos often carry. Files uploaded before the update are cleaned once, in the background, on the first start after updating; the logs report Upload metadata sweep finished when it is done. Nothing is required of you.
To run the clean-up again, for instance after restoring an old copy of the uploads, run it inside the running app, which keeps the files' owner unchanged (prefix
docker exec tymeslot
or cloudron exec --app <domain> --). It is safe to repeat:
bin/tymeslot rpc 'Tymeslot.Release.strip_upload_metadata()'
QuickTime (.mov) videos are no longer accepted as theme backgrounds. A
.mov
background you already have keeps working.
🛡️ Before You Upgrade
Complete these two steps before you touch the running instance:
1. Note the current version
Ask the running release for its version:
docker exec tymeslot bin/tymeslot versionWrite the version down. If you need to roll back, it is the image tag you return to.
2. Back up the database
Run this command before every upgrade to create a timestamped backup. For scheduled backups and the full restore procedure, see the Backup & Restore guide.
docker exec tymeslot su - postgres -c "pg_dump --clean --if-exists tymeslot" \
> backup-before-upgrade-$(date +%Y%m%d-%H%M%S).sql
The command prints nothing and writes the file to the current directory. 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 tymeslotYou 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 build Tymeslot from source instead of using the prebuilt image, update your checkout:
git pull origin main2 Apply the Update
Recreate the container from the new image. Your data volumes carry over:
# Prebuilt image
docker compose down
docker compose up -d
# Building from source: rebuild the image as well
docker compose -f docker-compose.build.yml down
docker compose -f docker-compose.build.yml up -d --buildStarted with docker run?
Pull the new tag, remove the old container and start a new one with the same volumes and the same
SECRET_KEY_BASE
value. Never let the command generate a fresh one: a new value signs everyone out and, unless
DATA_ENCRYPTION_KEY
is set, leaves every stored calendar, video and webhook credential unreadable.
Watch the startup logs
Tail the logs to confirm a clean startup:
docker logs -f tymeslotA successful startup prints Database migrations completed successfully, followed later 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 yourself. Tymeslot runs all pending Ecto migrations at startup, before it accepts traffic. Each one appears in the startup logs as a line beginning
== Running; if there are none, this release had no schema changes.
Upgrading to a release where environment variables take precedence
A variable that is set now outranks the admin settings page, which shows that setting greyed out. Older copies of
.env.example
had ENABLE_GOOGLE_AUTH=false,
ENABLE_GITHUB_AUTH=false
and
ENABLE_OAUTH_AUTH=false
uncommented. If your
.env
still has them, Google, GitHub and SSO sign-in stay off whatever you saved in the admin panel. Delete or comment out those lines, then restart. At startup, the logs carry a warning for every variable that overrides a value saved in the admin panel.
If the container fails to start after upgrading
A failed migration is the most common cause. Find the error in the logs:
docker logs tymeslot 2>&1 | grep -A 5 "ERROR\|migration"
If a migration failed, roll back as described below and open a GitHub issue with the full log output.
3 Confirm the Application Is Healthy
Check the container status and confirm the application responds:
# Check container status: it should show 'Up'
docker ps --filter name=tymeslot
# 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
while the application can reach its database and job queue. A
503
means it cannot do its job, so check the logs.
↩️ Rolling Back to a Previous Version
If the new version causes problems, these steps return you to the state before the upgrade. The database runs inside the Tymeslot container, so restore it first, while the new version is still running, then start the previous version:
1. Restore the pre-upgrade database backup
docker exec -i tymeslot \
su - postgres -c "psql -v ON_ERROR_STOP=1 --single-transaction tymeslot" \
< backup-before-upgrade-20260301-140000.sql
2. 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: luka1thb/tymeslot:latest
# To the previous version you noted, e.g.:
image: luka1thb/tymeslot:1.23.03. Start the previous version
docker compose up -d tymeslotRollback After Migrations May Leave the Schema Inconsistent
If the new version ran database migrations before failing, reverting only the image leaves a schema 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 at startup, before the application accepts traffic, so you never need to exec into the container for them. Each migration appears in the startup logs as a line beginning == Running;
the start script then prints
Database migrations completed successfully
whether or not there were any.
What if the new image fails to start after upgrading?
Find the error in the logs first; a failed migration is the most common cause:
docker logs tymeslot 2>&1 | grep -E "ERROR|migration"
If you cannot fix it quickly, roll back: restore the pre-upgrade backup and pin the previous image tag in docker-compose.yml, as described in the rollback section above. Restore the database whenever you revert the image; the old code does not understand a schema that newer migrations have changed.
Can I skip versions when upgrading?
Generally, yes. Migrations are cumulative: the new version applies every one you skipped, in order, on its first start. Major versions (N.0.0) may also need changes to environment variables or configuration files that no migration can make. Read the release notes on GitHub for every version you skip, and back up before every upgrade, however large the jump.
Will upgrading cause downtime?
Briefly, yes. Replacing the container typically takes under 30 seconds, and the application is unreachable for that time. Most self-hosted instances can live with that: upgrade outside your busy hours and tell users ahead of major releases. Zero-downtime upgrades need a load balancer and rolling deploys, which a single-container setup does not have.
I pulled the latest image but Docker says 'Image is up to date'. Am I already on the newest version?
Yes, if you are tracking the
latest
tag. Docker compares the published image digest with the one it has locally and downloads nothing if they match. To confirm which version is running, ask the release:
docker exec tymeslot bin/tymeslot version
If you pin a version tag (e.g. 1.24.0) in docker-compose.yml, change it 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
200when the app and database are up. -
Login succeeds. Sign in with an existing account to confirm the user table and session handling are intact.
-
Migrations completed. Run
docker logs tymeslot 2>&1 | grep -i migrationand look for Database migrations completed successfully from the latest start. -
Pre-upgrade backup is stored safely. Copy
backup-before-upgrade-*.sqlto off-site storage before deleting it from the server.
🔗 Related Articles
Backup & Restore
Back up Tymeslot with pg_dump and cron automation. Covers Docker volume backup for uploaded files and step-by-step recovery from a complete data loss.
Cloudron Deployment
Install Tymeslot on Cloudron in minutes. PostgreSQL, SSL certificates, email relay, and automatic updates are all provisioned and managed for you.