motovaultpro/docs/BUILD-SERVER-SETUP.md

# Build/Staging Server Setup Guide

Complete guide for setting up the build and staging server for MotoVaultPro CI/CD with Gitea Actions.

## Overview

The build server serves dual purposes:
1. **Build Server**: Builds Docker images and pushes to Gitea Package Registry
2. **Staging Server**: Runs full application stack at staging.motovaultpro.com

```
+-------------------+     +--------------------+
|   Gitea Server    |     |  Production Server |
| git.motovaultpro  |     |  (mvp-prod runner) |
| + Package Registry|     +----------+---------+
+--------+----------+                |
         |                           v
         v                  motovaultpro.com
+--------+----------+
| Build/Staging VPS |
| (mvp-build runner)|
+-------------------+
         |
         v
staging.motovaultpro.com
```

## Server Requirements

### Minimum Specifications

| Resource | Requirement |
|----------|-------------|
| CPU | 4 cores |
| RAM | 8GB |
| Storage | 100GB SSD |
| Network | 100Mbps+ |
| OS | Ubuntu 22.04 LTS / Debian 12 |

### Network Requirements

- Port 80/443 open (for staging.motovaultpro.com)
- Outbound HTTPS to git.motovaultpro.com
- SSH access for administration

---

## Installation Steps

### 1. Update System

```bash
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git ca-certificates gnupg jq
```

### 2. Install Docker Engine

```bash
# Add Docker's official GPG key
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Add the repository
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Verify installation
docker --version
docker compose version
```

### 3. Install act_runner

```bash
# Download act_runner binary
curl -L https://gitea.com/gitea/act_runner/releases/download/v0.2.13/act_runner-0.2.13-linux-amd64 -o /tmp/act_runner
sudo mv /tmp/act_runner /usr/local/bin/act_runner
sudo chmod +x /usr/local/bin/act_runner

# Verify installation
act_runner --version
```

### 4. Create act_runner User

```bash
# Create user for running act_runner
sudo useradd -r -m -s /bin/bash act_runner
sudo usermod -aG docker act_runner

# Create config directory
sudo mkdir -p /etc/act_runner
sudo chown act_runner:act_runner /etc/act_runner
```

### 5. Register Runner with Gitea

Get a registration token from: `git.motovaultpro.com/egullickson/motovaultpro/settings/actions/runners`

```bash
# Generate config
sudo -u act_runner act_runner generate-config > /etc/act_runner/config.yaml

# Register runner with staging/build label
sudo -u act_runner act_runner register --no-interactive \
  --instance https://git.motovaultpro.com \
  --token <REGISTRATION_TOKEN> \
  --name "Build/Staging Server" \
  --labels "mvp-build:host"
```

### 6. Create Systemd Service

```bash
cat << 'EOF' | sudo tee /etc/systemd/system/act_runner.service
[Unit]
Description=Gitea Actions Runner
After=docker.service network.target

[Service]
ExecStart=/usr/local/bin/act_runner daemon --config /etc/act_runner/config.yaml
WorkingDirectory=/home/act_runner
User=act_runner
Group=act_runner
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start
sudo systemctl daemon-reload
sudo systemctl enable act_runner --now
sudo systemctl status act_runner
```

---

## Staging Environment Setup

### 1. Clone Repository

```bash
sudo mkdir -p /opt/motovaultpro
sudo chown act_runner:act_runner /opt/motovaultpro
sudo -u act_runner git clone https://git.motovaultpro.com/egullickson/motovaultpro.git /opt/motovaultpro
```

### 2. Set Secrets Directory Permissions

The `secrets/app` directory exists in the repository. Set proper permissions:

```bash
sudo chown -R act_runner:act_runner /opt/motovaultpro/secrets
sudo chmod 700 /opt/motovaultpro/secrets/app
```

### 3. Configure DNS

Add DNS A record:
```
staging.motovaultpro.com -> <build-server-ip>
```

### 4. Configure Cloudflare (if using)

Ensure `staging.motovaultpro.com` is proxied through Cloudflare or has a valid SSL certificate configured.

### 5. Initialize Data Directories

```bash
cd /opt/motovaultpro
sudo mkdir -p data/backups data/documents
sudo chown -R 1001:1001 data/backups data/documents
```

---

## Docker Registry Authentication

### Login to Gitea Package Registry

```bash
# Login as act_runner user
sudo -u act_runner docker login git.motovaultpro.com -u egullickson
# Enter your Gitea access token when prompted
```

### Create Access Token

1. Go to `git.motovaultpro.com/user/settings/applications`
2. Create new token with scopes:
   - `read:packages`
   - `write:packages`
3. Save token securely

---

## Verification

### Check Runner Status

```bash
sudo systemctl status act_runner
```

### Check Runner Registration

Go to `git.motovaultpro.com/egullickson/motovaultpro/settings/actions/runners` and verify the runner appears as "Online".

### Test Docker Access

```bash
sudo -u act_runner docker info
sudo -u act_runner docker compose version
```

### Test Registry Push

```bash
# Build and push a test image
sudo -u act_runner docker build -t git.motovaultpro.com/egullickson/test:latest -f- . <<EOF
FROM alpine:latest
RUN echo "test"
EOF

sudo -u act_runner docker push git.motovaultpro.com/egullickson/test:latest
```

---

## Maintenance

### Disk Cleanup

```bash
# Create cleanup script
sudo tee /usr/local/bin/docker-cleanup.sh > /dev/null <<'EOF'
#!/bin/bash
# Remove unused Docker resources older than 7 days
docker system prune -af --filter "until=168h"
docker volume prune -f
EOF

sudo chmod +x /usr/local/bin/docker-cleanup.sh

# Add to crontab (run daily at 3 AM)
echo "0 3 * * * /usr/local/bin/docker-cleanup.sh >> /var/log/docker-cleanup.log 2>&1" | sudo crontab -
```

### Update Runner

```bash
# Download new version
curl -L https://gitea.com/gitea/act_runner/releases/download/v0.2.12/act_runner-0.2.12-linux-amd64 -o /tmp/act_runner
sudo mv /tmp/act_runner /usr/local/bin/act_runner
sudo chmod +x /usr/local/bin/act_runner

# Restart service
sudo systemctl restart act_runner
```

---

## Troubleshooting

### Runner Not Picking Up Jobs

```bash
# Check service status
sudo systemctl status act_runner

# View logs
sudo journalctl -u act_runner -f

# Check registration
sudo -u act_runner act_runner list
```

### Docker Permission Issues

```bash
# Ensure act_runner is in docker group
sudo usermod -aG docker act_runner

# Restart service
sudo systemctl restart act_runner
```

### Registry Authentication Failures

```bash
# Re-login to registry
sudo -u act_runner docker logout git.motovaultpro.com
sudo -u act_runner docker login git.motovaultpro.com -u egullickson
```

### Staging Not Accessible

```bash
# Check containers
docker ps

# Check Traefik logs
docker logs mvp-traefik-staging

# Check SSL certificate
curl -vI https://staging.motovaultpro.com
```

---

## Quick Reference

### Important Paths

| Path | Description |
|------|-------------|
| `/opt/motovaultpro` | Application root |
| `/opt/motovaultpro/secrets/app` | Application secrets |
| `/etc/act_runner/config.yaml` | Runner configuration |
| `/home/act_runner/.docker/config.json` | Registry credentials |

### Common Commands

```bash
# Runner management
sudo systemctl status act_runner
sudo systemctl restart act_runner
sudo journalctl -u act_runner -f

# Docker management
docker system df
docker system prune -af
docker ps
docker logs -f mvp-backend-staging

# Staging stack
cd /opt/motovaultpro
docker compose -f docker-compose.yml -f docker-compose.staging.yml ps
docker compose -f docker-compose.yml -f docker-compose.staging.yml logs -f
```