Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ptshen/timeful-plus/llms.txt

Use this file to discover all available pages before exploring further.

Keeping your Timeful instance updated and your data backed up are the two most important ongoing operations for any self-hosted deployment. This page covers both workflows for Docker Compose deployments — using either pre-built images from GHCR or a source build.

​
Updating Timeful

Pre-built images are published to GitHub Container Registry on every push to the main branch. Pulling and restarting takes under a minute with no build step required. 
make pull-ghcr
This runs docker compose -f docker-compose.ghcr.yml pull followed by docker compose -f docker-compose.ghcr.yml up -d and prints a confirmation message when done.
Available image tags:
TagMeaning
latestLatest stable build from the main branch
mainAlias for latest
<version>Specific version tags published at releases
<branch>-<sha>Builds from a specific commit

​
Option 2: Update from Source

If you customise the Timeful source code or prefer building locally: 
make pull
This runs git pull, then rebuilds all images with --no-cache, and brings the stack back up.
Always create a database backup before updating. See the Backup section below.

​
Database Backup

Backups are stored on the host at ./backups/backup-YYYYMMDD-HHMMSS/. Each backup is a mongodump snapshot of the schej-it database.

​
Creating a Backup

make backup
The Makefile target:
  1. Creates the ./backups/ directory if it does not exist.
  2. Runs mongodump --db=schej-it --out=/data/backup inside the timeful-mongodb container.
  3. Copies the result to ./backups/backup-YYYYMMDD-HHMMSS/ on the host.
  4. Prints ✅ Backup created in ./backups/.

​
Backup Storage Layout

./backups/
├── backup-20250115-083000/
│   └── schej-it/
│       ├── events.bson
│       ├── events.metadata.json
│       ├── users.bson
│       ├── users.metadata.json
│       └── ...
├── backup-20250116-083000/
│   └── schej-it/
│       └── ...
Automate backups with a cron job. A daily backup at 03:00 is a sensible default:
0 3 * * * cd /opt/timeful && make backup >> /var/log/timeful-backup.log 2>&1
FrequencyRetentionUse case
Daily7 daysTypical self-hosted team
Before every updateKeep until next updatePre-update safety net
Weekly4 weeksLow-traffic personal instance

​
Database Restore

Restoring overwrites all current data in the schej-it database. Back up first if you have unsaved changes.

​
Restoring from the Latest Backup

make restore
The Makefile target automatically picks the most recent directory in ./backups/, copies it into the container, and runs mongorestore --drop to replace the existing data.

​
Restoring from a Specific Backup

If make restore picks the wrong backup, use the manual steps above and substitute the directory name of the backup you want: 
docker cp ./backups/backup-20250110-120000 timeful-mongodb:/data/restore
docker compose exec mongodb mongorestore --db=schej-it /data/restore/schej-it --drop

​
Verifying a Backup

After creating a backup, spot-check the dump files to confirm they are non-empty: 
ls -lh ./backups/$(ls -t backups/ | head -1)/schej-it/
You should see .bson and .metadata.json files for each collection (events, users, responses, etc.) with non-zero sizes.

Docker Deployment

Full Docker Compose setup guide including initial configuration.

Security Hardening

Container security best practices for production deployments.

Build docs developers (and LLMs) love

Get started for freeTalk to us