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

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

2. Install Docker Engine

# 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

# 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

# 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

# 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

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

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:

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

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

# 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

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

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

Test Registry Push

# 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

Update Runner

# 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

# 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

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

# Restart service
sudo systemctl restart act_runner

Registry Authentication Failures

# 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

# 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

# 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