193 lines
4.2 KiB
Markdown
193 lines
4.2 KiB
Markdown
# 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```bash
|
||
#!/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:
|
||
|
||
```yaml
|
||
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:
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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
|
||
```
|