viewer/DEPLOYMENT_GUIDE.md

Deployment Guide - App Pipeline

Complete guide for deploying applications using the custom deployment pipeline with Gitea, Docker, and Traefik.

1. Create New Application

1.1 Gitea Repository

1. Log in to Gitea: https://git.appmodel.nl
2. Create a new repository:
   • Owner: Tour
   • Name: viewer (or your app name)

1.2 Generate Skeleton on Server

On the server, run:

apps-create viewer static-fe

This command:

• Sets up /opt/apps/viewer (attempts to clone from git@git.appmodel.nl:Tour/viewer.git)
• Generates a multi-stage Dockerfile for a Node-based static frontend
• Creates ~/infra/viewer/docker-compose.yml with:
  • Service viewer
  • Connection to traefik_net
  • Traefik route: https://viewer.appmodel.nl

2. Development & Build

On your development machine:

# Clone the repository
git clone git@git.appmodel.nl:Tour/viewer.git
cd viewer

# Build your app as usual
npm install
npm run build   # output goes to dist/

# Commit and push
git add .
git commit -m "First version"
git push

Note: The Dockerfile expects a dist/ directory containing static files.

3. Deployment Pipeline

3.1 Manual Deploy with app-deploy

On the server, use the generic deploy command:

app-deploy viewer

This command performs:

1. cd /opt/apps/viewer
2. git pull --ff-only
3. cd /home/tour/infra/viewer
4. docker compose up -d --build viewer

Logs are saved to: /var/log/app-deploy-viewer.log

3.2 Automatic Deployment via Gitea Hook

Set up automatic deployment on every push:

1. In Gitea, go to repository Tour/viewer
2. Navigate to Settings → Git Hooks
3. Select post-receive
4. Add the following script:

#!/usr/bin/env bash
/usr/local/bin/app-deploy viewer

Result: Every git push to Tour/viewer automatically triggers a deployment.

4. Traefik & DNS Configuration

Traefik Setup

Traefik runs in the traefik stack on the same server and manages:

• git.appmodel.nl
• auction.appmodel.nl
• aupi.appmodel.nl
• ... (new apps via labels)

Auto-Generated Labels

The apps-create command automatically adds the correct Traefik labels:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.viewer.rule=Host(`viewer.appmodel.nl`)"
  - "traefik.http.routers.viewer.entrypoints=websecure"
  - "traefik.http.routers.viewer.tls=true"
  - "traefik.http.routers.viewer.tls.certresolver=letsencrypt"
  - "traefik.http.services.viewer.loadbalancer.server.port=80"

DNS Configuration

Add a DNS record pointing to your server's public IP:

viewer.appmodel.nl → <server-public-ip>

Traefik + Let's Encrypt will automatically handle SSL certificate generation.

5. Future Application Types

The apps-create script currently supports:

• static-fe – Node build → Nginx → static frontend

Planned Types

Future app types can be added:

# Python API
apps-create stats api-py

# Background worker/crawler
apps-create crawler worker-py

Each type will have:

• Custom Dockerfile template
• Standard docker-compose.yml configuration
• Same deployment pipeline: app-deploy <name>

Quick Reference

Create and Deploy New App

# On server: create skeleton
apps-create viewer static-fe

# On dev machine: develop and push
git clone git@git.appmodel.nl:Tour/viewer.git
cd viewer
npm install
npm run build
git add .
git commit -m "Initial commit"
git push

# On server: deploy (or auto-deploys via hook)
app-deploy viewer

Existing Infrastructure

Service	URL	Description
Gitea	https://git.appmodel.nl	Git repository hosting
Auction	https://auction.appmodel.nl	Auction frontend
Aupi API	https://aupi.appmodel.nl	Auction backend API
Traefik	-	Reverse proxy & SSL

Log Locations

• Deployment logs: /var/log/app-deploy-<app-name>.log
• Docker logs: docker compose logs -f <service-name>

Useful Commands

# View deployment logs
tail -f /var/log/app-deploy-viewer.log

# View container logs
cd ~/infra/viewer
docker compose logs -f viewer

# Restart service
docker compose restart viewer

# Rebuild without cache
docker compose up -d --build --no-cache viewer