This GitHub action utilizes MIE's open source cluster to manage LXC containers derived from your github repository source code.

This GitHub Action offers two distinct pathways for managing containers on our Proxmox cluster:

Use your existing GitHub self-hosted runners or any external runner to automatically provision containers. No GitHub PAT required. You maintain full control over your runners and simply use our action to manage containers on the Proxmox cluster.

Our action automatically creates and manages GitHub runners for you. Each branch gets its own dedicated runner and container. Requires a GitHub PAT with runner management permissions. We handle runner lifecycle (creation/deletion) automatically.

1. Video Walkthroughs
2. Sequence Diagram
3. Prerequisites
4. Getting Started
   • Path 1: Using Your Own Runners
   • Path 2: Automatic Runner Provisioning
     • Personal Access Token Setup
     • Setup-Runner Job
     • Manage-Container Job
5. Configurations
   • Basic Properties
   • Automatic Deployment Properties
6. Important Notes for Automatic Deployment
7. Output
8. Sample Workflow Files
9. Misc.

I have created a series of videos to walk you through automatic deployment, both in GitHub and via the command line.

[Long-Form] Proxmox LaunchPad Walkthrough: Video
[Short-Form] Proxmox LaunchPad Demonstration: Short
[Long-Form] Automatic Deployment through Command Line: Video
[Long-Form] Getting Started with Creating LXC Continers with Proxmox: Video

The sequence diagram below describes the sequence of events executed by this Github Action.

sequenceDiagram
    participant Dev as Developer
    participant GH as GitHub
    participant GHAR as GitHub Actions Runner
    participant Prox as Proxmox Cluster
    participant LXC as LXC Container

    Dev->>GH: Push/Create/Delete branch
    GH->>GHAR: Trigger workflow

    alt Push/Create event
        GHAR->>Prox: Check if LXC container exists for branch
        alt Container does not exist
            GHAR->>Prox: Clone template, create LXC container
            Prox->>LXC: Start container, configure self-hosted runner (if automatic runner provisioning is enabled).
            GHAR->>LXC: Register self-hosted runner (if automatic runner provisioning is enabled).
            GHAR->>LXC: Run manage container job (install deps, clone repo, install services, deploy app)
        else Container exists
            GHAR->>Prox: Call update script
            Prox->>LXC: Update container contents, restart with latest branch
        end
    else Delete event
        GHAR->>LXC: Call delete-container script
        LXC->>Prox: Remove runner (if automatic runner provisioning is enabled) and delete LXC container
    end

• Proxmox Datacluster Setup that mirrors/forks https://github.com/mieweb/opensource-server.
• Valid Proxmox Account.

Both pathways require the following trigger events in your workflow file:

on:
  push:
  create:
  delete:

This allows a container to be created/updated on a push command, created when a new branch is created, and deleted when a branch is deleted (like in the case of an accepted PR).

If you have your own GitHub self-hosted runners or external runners, you can use them directly with our action. Simply create a workflow file with the manage-container job:

name: Proxmox Container Management

on:
  push:
  create:
  delete:

jobs:
  manage-container:
    runs-on: self-hosted  # or your runner label
    steps:
      - uses: maxklema/proxmox-launchpad@main
        with:
          proxmox_username: your-username
          proxmox_password: ${{ secrets.PROXMOX_PASSWORD }}
          # No github_pat needed for this path
          # Add other configuration options as needed

Benefits of Path 1:

• No GitHub PAT required
• Full control over runner environment
• Enhanced security
• Simpler workflow configuration

To use automatic runner provisioning, you must create a GitHub Personal Access Token with runner management permissions:

1. Navigate to your GitHub account settings
2. Click "Developer settings" (bottom left)
3. Navigate to "Personal Access Tokens (classic)"
4. Click "Generate new token"
5. Give your token a name and expiration date
6. Select the manage_runners:org permission (or manage_runners:enterprise for enterprise repositories)
7. Generate the token and store it securely
8. Add it as a repository secret named GH_PAT in your repository

For automatic runner provisioning, you need both a setup-runner job and a manage-container job:

name: Proxmox Container Management

on:
  push:
  create:
  delete:

jobs:
  setup-runner:
    runs-on: ubuntu-latest
    steps:
      - name: Install Dependencies
        run: |
          sudo apt install -y sshpass jq

      - uses: maxklema/proxmox-launchpad@main
        with:
          proxmox_username: your-username
          proxmox_password: ${{ secrets.PROXMOX_PASSWORD }}
          github_pat: ${{ secrets.GH_PAT }}

  manage-container:
    runs-on: self-hosted
    needs: setup-runner
    steps:
      - uses: maxklema/proxmox-launchpad@main
        with:
          proxmox_username: your-username
          proxmox_password: ${{ secrets.PROXMOX_PASSWORD }}
          github_pat: ${{ secrets.GH_PAT }}
          # Add other configuration options as needed

What happens with automatic runner provisioning:

• A new runner is created for each branch
• Runners are automatically deleted when branches are deleted
• Each branch gets its own dedicated container and runner
• Complete lifecycle management (no manual cleanup needed)

At the very minimum, two configuration settings are required to create any container. With all of these properties specified, you can create an empty container for a branch.

There are a few other properties that are not required, but can still be specified in the workflow file:

This github action can attempt to automatically deploy services on your container. This is done by fetching your repository contents on the branch that the script is being ran in, installing dependencies/services, and running build and start commands in the background.

Additionally, with automatic deployment enabled, your container will update on every push command automatically, preventing you from having to SSH into the container and setting it up manually.

There are two types of deployments: single component and multi-component deployment. Single component deployment involves deploying only a single service (i.e. a single Flask Server, REACT application, MCP Server, etc.). Multi-component deployment involves deploying more than one service at the same time (i.e. a flask backend and a vite.js backend).

• (*) These options are only required if root_start_command is not provided, as that command may be a docker build and/or a docker compose command that builds the entire application.

Below are some important things to keep in mind if you want your application to be automatically deployed:

• If you are using meteor, you must start your application with the flags --allow-superuser and --port 0.0.0.0:<http-port>.
  • Meteor is a large package, so deploying it may take more time than other applications.
• When running a service, ensure it is listening on 0.0.0.0 (your IP) instead of only locally at 127.0.0.1.
• The Github action will fail with an exit code and message if a property is not set up correctly.
• If you are using vite.js as a frontend service, you need to add the domain name of your container in the allowHosts array in your vite.config.js file.
• When specifying the path to the component, ensure it is relative to the project root directory. For example, if your project root is /home/user/my-project, and your component is located at /home/user/my-project/frontend, you should specify the path as ./frontend, frontend/, or frontend.

When a container is successfully created (Github Action is successful), you will see an output with all of your container details. This includes all your ports, container ID, container IP Address (internal in 10.15.x.x subnet), public domain name, and ssh command to access your container.

See an example output below:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔔  COPY THESE PORTS DOWN — For External Access
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📌  Note: Your container listens on SSH Port 22 internally,
    but EXTERNAL traffic must use the SSH port listed below:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅  Hostname Registration: polyglot-test-maxklema-pull-request → 10.15.129.23
🔐  SSH Port            : 2344
🌐  HTTP Port           : 32000
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦  Container ID        : 136
🌐  Internal IP         : 10.15.129.23
🔗  Domain Name         : https://polyglot-test-maxklema-pull-request.opensource.mieweb.org
🛠️  SSH Access          : ssh -p 2344 root@polyglot-test-maxklema-pull-request.opensource.mieweb.org
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
NOTE: Additional background scripts are being ran in detached terminal sessions.
Wait up to two minutes for all processes to complete.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Still not working? Contact Max K. at maxklema@gmail.com
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

name: Proxmox Container Management (Own Runners)

on:
  push:
  create:
  delete:

jobs:
  manage-container:
    runs-on: self-hosted  # Use your own runner
    steps:
      - uses: maxklema/proxmox-launchpad@main
        with:
          proxmox_username: your-username
          proxmox_password: ${{ secrets.PROXMOX_PASSWORD }}
          container_env_vars: '{"API_KEY": "1234"}'
          install_command: npm i
          start_command: npm start
          runtime_language: nodejs
          services: '["mongodb"]'

name: Proxmox Container Management (Auto Runners)

on:
  push:
  create:
  delete:

jobs:
  setup-runner:
    runs-on: ubuntu-latest
    steps:
      - name: Install Dependencies
        run: |
          sudo apt install -y sshpass jq
      - uses: maxklema/proxmox-launchpad@main
        with:
          proxmox_username: your-username
          proxmox_password: ${{ secrets.PROXMOX_PASSWORD }}
          github_pat: ${{ secrets.GH_PAT }}

  manage-container:
    runs-on: self-hosted
    needs: setup-runner
    steps:
      - uses: maxklema/proxmox-launchpad@main
        with:
          proxmox_username: your-username
          proxmox_password: ${{ secrets.PROXMOX_PASSWORD }}
          github_pat: ${{ secrets.GH_PAT }}
          container_env_vars: '{"API_KEY": "1234"}'
          install_command: npm i
          start_command: npm start
          runtime_language: nodejs
          services: '["mongodb"]'

Written by maxklema.
Feel free to submit a PR/issue here.