Docker Swarm Service Deployment Utility

🚀 Automated Docker Swarm deployment utility with OpenBao/Vault integration and Forgejo Actions

This repository provides a complete deployment utility that can be executed from other repositories via Forgejo Actions workflows. It handles secret management, configuration file deployment, and Docker Swarm stack deployment through Portainer API integration.

Features

• ✅ Remote Execution: Deploy from any repository using Forgejo Actions
• ✅ Secret Management: Automatic secret generation and management via OpenBao/Vault
• ✅ Multi-Environment: Support for production, staging, and render environments
• ✅ Configuration Files: Deploy additional config files with secret substitution
• ✅ Portainer Integration: Deploy via Portainer API with proper endpoint routing
• ✅ Manual Controls: Optional manual deployment restrictions for sensitive stacks
• ✅ Debug Support: Comprehensive logging and troubleshooting capabilities

Quick Start for Application Repositories

1. Copy the Workflow

Copy the deployment workflow to your application repository:

# In your application repository
mkdir -p .forgejo/workflows
curl -fsSL https://forgejo.hrt.gg/maddi/swarm-service-template/raw/branch/main/forgejo-workflows/deploy-swarm-service.yml \
     -o .forgejo/workflows/deploy-swarm-service.yml

2. Configure Secrets

Add these secrets to your repository (Settings → Secrets):

• PORTAINER_API_KEY - Your Portainer API key
• PORTAINER_URL - Portainer server URL
• VAULT_TOKEN - OpenBao/Vault authentication token
• VAULT_URL - OpenBao/Vault server URL
• VAULT_BASE_PATH - Base path in Vault for secrets

3. Create Your Service

Create docker-compose.yml in your repository:

services:
  app:
    image: your-registry.com/your-app:latest
    environment:
      DB_PASSWORD: ${DB_PASSWORD}  # Auto-generated secret
    networks:
      - npm-internal
    
x-vault-secrets:
  DB_PASSWORD:
    directive: "VAULT:db-password"

4. Deploy

Push to deployment branches:

• main or production → Production
• staging → Staging
• render → Render & Runner

How It Works

1. Trigger: Push to deployment branch or manual workflow dispatch
2. Download: Forgejo runner downloads the deployment script from this repository
3. Execute: Script clones this repo, installs dependencies, and runs deployment pipeline
4. Secrets: Parses compose file and provisions secrets via OpenBao/Vault
5. Deploy: Deploys stack via Portainer API to appropriate environment
6. Configure: Processes extra configuration files with secret substitution

Deployment Script Usage

You can also run the deployment script directly:

# Set required environment variables
export STACK_NAME="my-app"
export ENVIRONMENT="prod"
export PORTAINER_API_KEY="your-key"
export PORTAINER_URL="https://portainer.example.com"
export VAULT_TOKEN="your-token"
export VAULT_URL="https://vault.example.com"
export VAULT_BASE_PATH="secret/swarm"

# Download and run
curl -fsSL https://forgejo.hrt.gg/maddi/swarm-service-template/raw/branch/main/deploy-swarm-service.sh | bash

Repository Contents

Core Utility

• deploy-swarm-service.sh - Main deployment script for remote execution
• .forgejo/scripts/ - Deployment pipeline scripts (secret management, Portainer API)
• .forgejo/workflows/ - Original template workflows (legacy)

For Application Repositories

• forgejo-workflows/ - Ready-to-use Forgejo Actions workflows
• examples/ - Complete example applications
• SETUP.md - Comprehensive setup guide
• docker-compose.yml - Reference template

Documentation

• README.md - This file (overview and quick start)
• SETUP.md - Detailed setup and configuration guide
• forgejo-workflows/README.md - Workflow documentation
• examples/*/README.md - Example-specific documentation

Architecture

Deployment Flow

Application Repo → Forgejo Actions → Download Utility → Deploy to Swarm
     ↓                    ↓                ↓               ↓
docker-compose.yml   Workflow Runs   Execute Script   Portainer API
extra-files/         Download Script   Parse Secrets   Secret Management  
Secrets Config       Install Deps      Provision Files Stack Deployment

Environment Mapping

• Production: main/production branches → Portainer Endpoint 1
• Staging: staging branch → Portainer Endpoint 5
• Render: render branch → Portainer Endpoint 6

Secret Management

• Secrets defined in x-vault-secrets section of docker-compose.yml
• Auto-generated via OpenBao/Vault with configurable generation rules
• Shared between docker-compose and extra configuration files
• Environment-specific storage: {base-path}/{stack-name}/{environment}/{secret}

Examples

Basic Web Application

See examples/simple-webapp/ for a complete example featuring:

• Multi-service stack (app + database)
• Automatic secret generation
• Configuration file deployment
• NPM integration setup

Quick Example

# docker-compose.yml
services:
  app:
    image: my-app:latest
    environment:
      DATABASE_URL: postgres://user:${DB_PASSWORD}@db/${DB_NAME}
      
x-vault-secrets:
  DB_PASSWORD:
    directive: "VAULT:db-password"
  DB_NAME:
    directive: "VAULT:password:16"

Advanced Features

Extra Configuration Files

Deploy additional config files with secret substitution:

1. Create extra-files/ directory with your config files
2. Create extra-files-manifest.yml defining destinations and secrets
3. Files automatically deployed with secrets substituted

Manual Deployment Control

Create .manual-stacks file to prevent auto-deployment for sensitive services.

Environment Overrides

Use environment-specific compose files:

• docker-compose.prod.yml
• docker-compose.staging.yml

Debug and Force Options

• Manual workflow dispatch with debug logging
• Force redeployment without changes
• Selective secret regeneration