​
Folder Structure

MOPS/
├── environments/
│   ├── dev/
│   │   ├── n8n/
│   │   │   ├── .env
│   │   │   └── docker-compose.yml
│   │   └── traefik/
│   ├── staging/
│   │   ├── n8n/
│   │   └── traefik/
│   └── prod/
│       ├── n8n/
│       └── traefik/
├── shared/              # Reserved for shared future config fragments
└── README.md

​
Stack Naming (Portainer)

  • Format: [env]-[service]-stack
  • Examples:
    • dev-n8n-stack
    • prod-n8n-stack
    • staging-traefik-stack
All container, volume, and network names follow the same prefixing rule.

​
Environments

​
dev/

  • Used for experiments, rapid iteration, test credentials only.
  • Safe to break.
  • Only accessible to internal team.

​
staging/

  • Used for internal QA.
  • Should mirror prod config and infrastructure 1:1 as closely as possible.
  • Uses real integration endpoints (e.g., SMTP, OAuth), but not production data.

​
prod/

  • Production-only.
  • Zero downtime expectation.
  • Code and config must flow from staging, not directly from dev.

​
Workflow Summary

  1. Develop in dev/
    • Work with live containers locally or via Portainer Stack.
    • Debug, test new features, iterate quickly.
  2. Promote to staging/
    • Use rsync or git to copy the working config.
    • Replace test .env values with real sandbox/QA credentials.
    • Run end-to-end test flows.
  3. Promote to prod/
    • Only after staging passes.
    • Tag commit (v1.2.0-prod), deploy via CI/CD or Portainer Git Stack.
    • Document changes and review logs post-deploy.

​
Secrets Management

​
Current State

.env files are stored in Git — this is not secure.

​
Immediate Fix

  • Move .env values to Portainer Secrets (per environment).
  • Reference them in docker-compose.yml like this:
env_file:
  - /run/secrets/n8n_api_key

​
Near-Future Upgrade Path

  • Use dotenv-vault or [SOPS + Git-crypt] for OSS secret encryption.
  • Alternative: GitHub Actions + [secrets manager] for automated secure injection.

​
CI/CD Plan

​
Goals

  • Push to environments/prod/** requires PR approval and triggers deploy to prod
  • Push to environments¸/staging/** triggers deploy to staging

​
Tool: GitHub Actions

on:
  push:
    paths:
      - 'environments/staging/**'
    branches:
      - main

jobs:
  deploy-staging:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy to Staging
        run: |
          ssh user@server 'cd /docker && docker compose -f environments/staging/n8n/docker-compose.yml up -d'
Add manual approval + backup steps for prod.

​
Backup & Rollback Plan

​
For PostgreSQL (n8n, mautic):

  • Use pg_dump and pg_restore.
  • Set up nightly cron-based backup containers.

​
For Volumes:

  • Use [bind mounts] to make data externally accessible.
  • Snapshot /var/lib/docker/volumes regularly using rsync or Btrfs/ZFS snapshots.

​
Best Practices

  • Never deploy to prod directly.
  • Never store .env with secrets in Git.
  • Always test in staging before production.
  • Always prefix stacks/networks/containers with [env]-[service].
  • Always document new services in their README.md.
  • Avoid floating Docker image tags in prod (e.g., use n8nio/n8n:1.27.1 not :latest).

​
Future Improvements

  • Central secrets manager
  • Automated rollback script
  • Infra diagram / dependency map
  • Multi-server orchestration (Docker Swarm or K8s)
  • Terraform/Ansible for provisioning VPSes
Questions? Ping Jordan or Joe. Otherwise: build, test, promote. Stay sharp. git config —global pull.rebase true