Deploy Timeful with Docker Compose — Self-Hosting Guide

Timeful ships as a three-container application — MongoDB, a Go backend, and a Vue.js frontend — all wired together with a single Docker Compose file. You can be running at http://localhost:3002 in under five minutes using the pre-built images from GitHub Container Registry (GHCR), or build everything locally if you need to customise the source.

Prerequisites

Docker 20.10 or later
Docker Compose v2.0 or later
A cloned copy of the repository (for configuration files):

git clone https://github.com/schej-it/timeful.app.git
cd timeful.app

Deployment Options

Pre-built Images (Recommended)
Build from Source

The fastest path to a running instance. Images for both amd64 and arm64 are published automatically on every push to main.Step 1 — Pull the images

docker pull ghcr.io/lillenne/timeful.app/backend:latest
docker pull ghcr.io/lillenne/timeful.app/frontend:latest

Step 2 — Configure the environment

cp .env.example .env
cp config.example.js config.js
# Generate and paste a secure key
echo "ENCRYPTION_KEY=$(openssl rand -base64 32)" >> .env

Step 3 — Start the stack

docker compose -f docker-compose.ghcr.yml up -d

Or with the Makefile shortcut:

make up-ghcr

Updating to the latest version

# Pull new images and recreate containers
docker compose -f docker-compose.ghcr.yml pull
docker compose -f docker-compose.ghcr.yml up -d

# Or with the Makefile
make pull-ghcr

Use this path when you want to modify the source code or test local changes before deploying. The base docker-compose.yml runs the frontend as a Vue.js development server (node:20-alpine) rather than the production Nginx image.Option A — Automated setup (recommended)The included shell script checks your environment, creates a .env from the template, and starts the stack:

./docker-setup.sh

Option B — Makefile

make setup   # runs docker-setup.sh interactively
make up      # docker compose up -d

Option C — Manual

cp .env.example .env
cp config.example.js config.js
# Edit .env and set at minimum ENCRYPTION_KEY
docker compose up -d

Docker Compose will build the Go backend and Vue.js frontend images, pull MongoDB 6.0, and start all three containers in the correct dependency order.Rebuilding after a source change

git pull
docker compose down
docker compose build --no-cache
docker compose up -d

Accessing the Application

Once the stack is healthy, open:

URL	Description
`http://localhost:3002`	Main Timeful application
`http://localhost:3002/swagger/index.html`	Interactive API documentation

The frontend container proxies all /api and /sockets/ traffic to the backend, so only a single port (3002) needs to be reachable from your browser. The backend container is intentionally not exposed to the host.

Makefile Command Reference

The repository ships with a Makefile that wraps common Docker Compose operations. Run make help to see all commands.

Command	Description
`make setup`	Run interactive initial setup via `docker-setup.sh`
`make build`	Build Docker images from source
`make up`	Start the stack (build from source)
`make up-ghcr`	Start the stack using GHCR pre-built images
`make down`	Stop all containers
`make down-ghcr`	Stop containers (GHCR variant)
`make restart`	Restart all services
`make restart-ghcr`	Restart services (GHCR variant)
`make logs`	Follow logs for all services
`make logs-ghcr`	Follow logs for all services (GHCR variant)
`make logs-backend`	Follow backend logs only
`make logs-frontend`	Follow frontend logs only
`make logs-db`	Follow MongoDB logs only
`make pull`	Pull source changes, rebuild, and restart
`make pull-ghcr`	Pull latest GHCR images and restart
`make status`	Show container status
`make status-ghcr`	Show container status (GHCR variant)
`make backup`	Dump MongoDB to `./backups/`
`make restore`	Restore from the most recent backup
`make shell-backend`	Open a shell in the backend container
`make shell-frontend`	Open a shell in the frontend container
`make shell-db`	Open a `mongosh` session against `schej-it`
`make dev`	Start in development mode with live logs
`make dev-build`	Build and start in development mode
`make clean`	Stop containers and delete all volumes ⚠️
`make clean-ghcr`	Stop containers and delete volumes (GHCR variant) ⚠️

Docker Image Tags

Both the backend and frontend images are published to GitHub Container Registry under the ghcr.io/lillenne/timeful.app namespace.

Image	Tag	Description
`ghcr.io/lillenne/timeful.app/backend`	`latest`	Latest stable build from `main`
`ghcr.io/lillenne/timeful.app/frontend`	`latest`	Latest stable build from `main`
`…/backend`	`main`	Alias for `latest`
`…/backend`	`<version>`	Pinned release (e.g. `v1.2.0`)
`…/backend`	`<branch>-<sha>`	Specific commit build

Pin to a specific version tag in production so that docker compose … pull does not automatically roll out an untested release.

Architecture

The Compose stack runs three containers that communicate over an internal bridge network named timeful-network. Pre-built images (docker-compose.ghcr.yml):

Container	Image	Internal port	Host port
`timeful-mongodb`	`mongo:6.0`	`27017`	`27017`
`timeful-backend`	`ghcr.io/…/backend:latest`	`3002`	(not exposed)
`timeful-frontend`	`ghcr.io/…/frontend:latest` (Nginx)	`80`	`3002`

Build from source (docker-compose.yml):

Container	Image	Internal port	Host port
`timeful-mongodb`	`mongo:6.0`	`27017`	`27017`
`timeful-backend`	built locally	`3002`	(not exposed)
`timeful-frontend`	`node:20-alpine` (Vue dev server)	`8080`	`3002`

The production frontend (GHCR image) uses Nginx to proxy /api and /sockets/ to the backend, serves the pre-built Vue.js bundle from /usr/share/nginx/html, and caches static assets for one year. The development frontend runs the Vue CLI dev server directly.

Configuration

Set environment variables for OAuth, email, and premium features

Production Setup

Add a reverse proxy, custom domain, and HTTPS

Podman

Run rootless with Podman Compose or systemd Quadlets

Updates & Backups

Automate rolling updates and database snapshots

Getting Started

Self-Hosting

Features

Deployment Guides

Operations

Deploy Timeful with Docker Compose — Self-Hosting Guide

Prerequisites

Deployment Options

Accessing the Application

Makefile Command Reference

Docker Image Tags

Architecture

Configuration

Production Setup

Podman

Updates & Backups

Build docs developers (and LLMs) love

Getting Started

Self-Hosting

Features

Deployment Guides

Operations

Documentation Index

​Prerequisites

​Deployment Options

​Accessing the Application

​Makefile Command Reference

​Docker Image Tags

​Architecture

Configuration

Production Setup

Podman

Updates & Backups

Build docs developers (and LLMs) love

Prerequisites

Deployment Options

Accessing the Application

Makefile Command Reference

Docker Image Tags

Architecture