towerops-agent/DEPLOYMENT.md

Towerops Agent - Deployment Guide

GitLab CI/CD Pipeline

The agent uses GitLab CI/CD to automatically build and publish Docker images to the GitLab Container Registry.

Pipeline Stages

1. Test - Compile, format check, and lint
2. Build - Build Docker image
3. Release - Tag and publish versioned releases

Image Tags

Git Action	Image Tags	Example
Push to branch	<branch>, <commit-sha>	feat-snmp, abc123
Push to main	latest, main-<sha>	latest, main-abc123
Create tag	<version>, <tag>, latest	0.1.0, v0.1.0, latest

Registry Location

All images are pushed to:

registry.gitlab.com/graham/towerops-agent

Creating a Release

1. Update Version

In Cargo.toml:

[package]
name = "towerops-agent"
version = "0.2.0"  # ← Update this
edition = "2021"

2. Commit and Tag

git add Cargo.toml
git commit -m "Release v0.2.0"
git tag v0.2.0
git push origin main --tags

3. CI Pipeline Runs

GitLab CI will automatically:

• Run tests (cargo check, fmt, clippy)
• Build Docker image
• Tag as: 0.2.0, v0.2.0, latest
• Push to registry

4. Verify Release

Check the Container Registry:

https://gitlab.com/graham/towerops-agent/container_registry

You should see:

• latest (updated)
• 0.2.0 (new)
• v0.2.0 (new)

Using the Images

Pull Latest

docker pull registry.gitlab.com/graham/towerops-agent:latest

Pull Specific Version

docker pull registry.gitlab.com/graham/towerops-agent:0.1.0

Docker Compose

Update docker-compose.yml:

services:
  towerops-agent:
    image: registry.gitlab.com/graham/towerops-agent:latest
    # Or pin to specific version:
    # image: registry.gitlab.com/graham/towerops-agent:0.1.0
    environment:
      - TOWEROPS_API_URL=https://app.towerops.com
      - TOWEROPS_AGENT_TOKEN=${AGENT_TOKEN}
    volumes:
      - ./data:/data

Customer Deployment

Provide to Customers

Option 1: Docker Compose (Recommended)

Create docker-compose.yml:

version: '3.8'
services:
  towerops-agent:
    image: registry.gitlab.com/graham/towerops-agent:latest
    container_name: towerops-agent
    restart: unless-stopped
    environment:
      - TOWEROPS_API_URL=https://app.towerops.com
      - TOWEROPS_AGENT_TOKEN=<GET_FROM_UI>
    volumes:
      - ./data:/data

Instructions for customer:

# 1. Get agent token from Towerops UI
# 2. Replace <GET_FROM_UI> in docker-compose.yml
# 3. Start agent
docker-compose up -d

# 4. Check logs
docker-compose logs -f

# 5. Check status
docker-compose ps

Option 2: Docker Run

docker run -d \
  --name towerops-agent \
  --restart unless-stopped \
  -e TOWEROPS_API_URL=https://app.towerops.com \
  -e TOWEROPS_AGENT_TOKEN=<token> \
  -v $(pwd)/data:/data \
  registry.gitlab.com/graham/towerops-agent:latest

CI/CD Configuration

Required GitLab Variables

No additional CI/CD variables needed. GitLab provides these automatically:

• CI_REGISTRY - GitLab Container Registry URL
• CI_REGISTRY_USER - Username for registry login
• CI_REGISTRY_PASSWORD - Password for registry login

These are automatically available in all GitLab CI/CD pipelines.

Pipeline Triggers

Automatic:

• Push to any branch → test + build with branch tag
• Push to main → test + build + tag as latest
• Create tag (e.g., v0.1.0) → test + build + release

Manual: No manual triggers configured (all automatic)

Viewing Pipeline Status

1. Go to: https://gitlab.com/graham/towerops-agent/-/pipelines
2. Click on a pipeline to see detailed logs
3. Check job logs if build fails

Local Development

Build Locally

# Development build
cargo build

# Release build (optimized)
cargo build --release

# Build Docker image locally
docker build -t towerops-agent:local .

# Test local image
docker run --rm \
  -e TOWEROPS_API_URL=http://host.docker.internal:4000 \
  -e TOWEROPS_AGENT_TOKEN=test-token \
  -v $(pwd)/test-data:/data \
  towerops-agent:local

Test Before Pushing

# Check compilation
cargo check --release

# Format check
cargo fmt -- --check

# Lint check
cargo clippy -- -D warnings

# All together (what CI runs)
cargo check --release && \
cargo fmt -- --check && \
cargo clippy -- -D warnings

Rollback Procedure

If Latest Version Has Issues

Option 1: Revert Tag

# Find previous working version
git tag -l

# Delete bad tag locally and remotely
git tag -d v0.2.0
git push origin :refs/tags/v0.2.0

# Customers can use previous version
docker pull registry.gitlab.com/graham/towerops-agent:0.1.0

Option 2: Quick Fix

# Fix the issue
git commit -m "Hotfix: fix critical bug"

# Create patch version
git tag v0.2.1
git push origin main --tags

# New pipeline builds v0.2.1 and updates latest

Option 3: Pin Customers to Known Good Version

Update customer docker-compose.yml:

image: registry.gitlab.com/graham/towerops-agent:0.1.0  # Pin to working version

Multi-Architecture Support (Optional)

To support ARM devices (Raspberry Pi, etc.), uncomment the multi-arch section in .gitlab-ci.yml.

This will build for:

• linux/amd64 (x86_64 servers)
• linux/arm64 (ARM servers, Raspberry Pi 4+)

Note: Multi-arch builds take longer (~2x build time).

Monitoring Deployments

Check Image Size

docker images registry.gitlab.com/graham/towerops-agent

Expected size: 10-20 MB

Check Registry Usage

GitLab provides 10 GB of free registry storage. Monitor usage at:

https://gitlab.com/graham/towerops-agent/-/packages

Cleanup Old Images

GitLab has automatic cleanup policies. Configure at:

Settings → Packages & Registries → Container Registry → Cleanup policies

Recommended settings:

• Keep most recent: 10 tags
• Keep tags matching: ^v\d+\.\d+\.\d+$ (versions)
• Remove tags older than: 90 days

Troubleshooting

Pipeline Fails at Test Stage

Symptom: cargo check or cargo clippy fails

Fix:

# Run locally to see errors
cargo check --release
cargo clippy -- -D warnings

# Fix issues and push
git add .
git commit -m "Fix clippy warnings"
git push

Pipeline Fails at Build Stage

Symptom: Docker build fails

Fix:

# Test Docker build locally
docker build -t test .

# Check Dockerfile syntax
# Check .dockerignore isn't excluding needed files

Image Too Large

Symptom: Image is >50 MB

Fix:

• Check release profile in Cargo.toml (should have strip = true)
• Verify multi-stage build is working
• Check for large files in context (review .dockerignore)

Can't Pull Image

Symptom: docker pull fails with authentication error

Fix:

# Login to GitLab registry
docker login registry.gitlab.com
# Username: your GitLab username
# Password: personal access token with read_registry scope

# Or use deploy token (for customers)
# Create at: Settings → Repository → Deploy tokens

Security

Container Scanning (Optional)

Add to .gitlab-ci.yml for security scanning:

include:
  - template: Security/Container-Scanning.gitlab-ci.yml

container_scanning:
  stage: test
  variables:
    CS_IMAGE: $REGISTRY/$IMAGE_NAME:$CI_COMMIT_SHORT_SHA

Private Registry Access

For customers needing private access:

1. Create deploy token:

   • Go to: Settings → Repository → Deploy tokens
   • Name: customer-deploy-token
   • Scopes: read_registry
   • Copy username and token

2. Provide to customer:

docker login registry.gitlab.com
# Username: <deploy-token-username>
# Password: <deploy-token>

Support

For issues with deployment:

1. Check pipeline logs in GitLab
2. Review CLAUDE.md for architecture details
3. Test locally with docker build
4. Check GitLab registry status page

---

Last Updated: January 9, 2026 Registry: registry.gitlab.com/graham/towerops-agent Current Version: 0.1.0 (pre-release)