Introduction to ForgePod

ForgePod is your self-hosted Platform-as-a-Service powered by Podman — deploy containerized applications to your own infrastructure with a single API call. Multi-node cluster architecture with automatic load balancing, built-in monitoring, and zero Docker dependency.

Prerequisites

ForgePod is extremely lightweight. You can run it on almost any Linux server.

System Requirements

OS: Ubuntu 24.04 LTS (recommended)
RAM: 1 GB minimum
CPU: 1 Core minimum

Installation

ForgePod uses a single script to set up everything. By default, this will install both the Control Plane and a local Worker on your server.

Install ForgePod (one-command setup):

curl -sSL https://forgepod.dev/install.sh | bash

This single command installs everything you need:

Database: PostgreSQL & Redis for state management.
Engine: Podman v5 for running containers (Zero-Docker!).
Proxy: Traefik for automatic routing and SSL.
Worker: A local worker agent ready to receive deployments.

Verify Your Setup

Once finished, you should see your local node listed as active:

curl http://localhost:8080/nodes

Troubleshooting

Issue	Solution
`forgepod-api` fails to start	Check PostgreSQL: `systemctl status postgresql`
Worker not in `/nodes`	Check `CONTROL_PLANE_URL` env, verify connectivity
Podman v5 not installed	Run `apt-cache policy podman` to verify pinning
Traefik unreachable	Check `ufw status`, ensure port 80 is open

Quick Start

Once ForgePod is installed, you can deploy your first application with one command. For example, let's deploy two instances of Nginx:

        curl -X POST http://localhost:8080/deploy -H "Content-Type: application/json" -d '{"name": "demo", "image": "nginx", "replicas": 2}'
      

ForgePod will automatically:

Pull the Nginx image.
Create two containers across your cluster.
Configure the load balancer.
Make your app available at http://demo.apps.local

API Reference

Base URL: http://CONTROL_PLANE_IP:8080 · Interactive Swagger UI at /docs

Method	Endpoint	Description
GET	`/health`	Liveness probe — returns `{"status": "ok"}`
GET	`/readyz`	Readiness probe — verifies database connection
POST	`/deploy`	Deploy a new app or update existing
POST	`/scale`	Scale app to desired replica count
GET	`/apps`	List all deployed applications
GET	`/apps/{name}/logs`	Stream aggregated logs
POST	`/stop/{name}`	Stop all containers, remove route
GET	`/nodes`	List worker nodes with status
POST	`/internal/node/register`	Register worker (internal)
POST	`/internal/node/heartbeat/{hostname}`	Heartbeat ping every 30s

Example: Deploying an App

Request

curl -X POST http://localhost:8080/deploy -H "Content-Type: application/json" -d '{"name": "myapp", "image": "nginx", "replicas": 2}'

Response

{
  "status": "deployed",
  "url": "http://myapp.apps.local",
  "replicas_running": 2
}

CLI Reference

If you prefer using a terminal instead of raw curl, use forgepodctl:

Deploy a new app

forgepodctl deploy demo nginx --replicas 2

List all apps

forgepodctl apps

View app logs

forgepodctl logs demo

Stop an app

forgepodctl stop demo

DNS & Cloudflare

To access your apps via a domain name (like myapp.yourdomain.com), point these records to your Control Plane server's IP:

Type	Name	Points To
`A`	`api`	`YOUR_SERVER_IP`
`A`	`*.apps`	`YOUR_SERVER_IP`

The wildcard *.apps allows any app you deploy to be reached automatically without manual DNS changes.

Local Setup (Mac)

Want to try ForgePod on your Mac? Use Podman for a lightweight experience without Ubuntu.

1. Setup Podman

make podman-setup && podman machine start

2. Setup Go & Tools

make deps

3. Run Services

make dev-api dev-worker

Uninstall

Works on both control plane and worker nodes:

curl -sSL https://forgepod.dev/uninstall.sh | bash