Podman Deployer

A reusable set of scripts and utilities for bootstrapping and deploying Podman Quadlet container configurations and managing 1Password-backed secrets in rootless Podman environments.

This repository is designed to be pulled into your deployment/configuration projects (which contain the actual quadlets and site configurations) either as a submodule, a secondary repository checked out during CI/CD, or as a standalone CLI tool.

Repository Structure

• deploy.sh: The unified deployment entrypoint script. Handles syncing files, running the bootstrapper, provisioning secrets, and reloading systemd user services.
• bootstrap.sh: Host bootstrapping script. Installs Podman, 1Password CLI, system requirements, lingering setup, and the local gatekeeper reverse proxy.
• bin/: Helper utilities deployed to the target server's /usr/local/bin/:
  • podman-1p-lookup.sh: The custom 1Password credentials provider.
  • provision_secret.sh: Provisions a single Podman shell-driver secret.
  • provision_all_secrets.sh: Iterates through site directories to batch-provision mapped secrets.
  • podmanps: A formatted process status viewer.
• rootbootstrap/: Root-level configurations for the systemd-managed gatekeeper:
  • gatekeeper.container: Gatekeeper definition.
  • haproxy.cfg: HAProxy configuration.

Setup & CI/CD Integration

Forgejo / Gitea Actions

To use this deployer in your CI/CD pipelines, checkout this repository alongside your main repository that contains the sites/ directory:

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Quadlets Repository
        uses: actions/checkout@v4

      - name: Checkout Deployer Repository
        uses: actions/checkout@v4
        with:
          repository: sdickinson/podman-deployer
          path: deployer

      - name: Setup SSH
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.DEPLOY_SSH_KEY }}" > ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa
          ssh-keyscan -H ${{ secrets.DEPLOY_HOST }} >> ~/.ssh/known_hosts

      - name: Execute Deploy Script
        env:
          OP_TOKEN: ${{ secrets.OP_TOKEN }}
        run: |
          ./deployer/deploy.sh \
            --host "${{ secrets.DEPLOY_HOST }}" \
            --user "${{ secrets.DEPLOY_USER }}" \
            --path "${{ secrets.DEPLOY_PATH }}" \
            --dns "${{ secrets.BASE_SERVER }}" \
            --op-creds "${{ secrets.DEPLOY_1PASSWORD_JSON }}"

Local Usage

You can also run the deployer locally. Clone this repository adjacent to your quadlets repository, then call it from your quadlets repository root:

../podman-deployer/deploy.sh \
  --host "your-server-ip" \
  --user "ssh-user" \
  --path "/home/ssh-user/podman" \
  --dns "your-domain.com"

The script will automatically detect and load settings from a local .env.test file if present, and prompt interactively for missing variables if run in a TTY.