1

DEPLOYMENT_GUIDE

michael1986 edited this page 2025-12-02 12:54:43 +01:00

Table of Contents

• Deployment Guide - App Pipeline
• 1. Create New Application
• 1.1 Gitea Repository
• 1.2 Generate Skeleton on Server
• 2. Development & Build
• 3. Deployment Pipeline
• 3.1 Manual Deploy with app-deploy
• 3.2 Automatic Deployment via Gitea Hook
• 4. Traefik & DNS Configuration
• Traefik Setup
• Auto-Generated Labels
• DNS Configuration
• 5. Future Application Types
• Planned Types
• Quick Reference
• Create and Deploy New App
• Existing Infrastructure
• Log Locations
• Useful Commands

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

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