API Self-Hosted v3 – Podman Deployment Guide

Complete guide for deploying Draftable API Self-Hosted v3 using Podman and Podman Compose as an alternative to Docker.

This guide provides step-by-step instructions for deploying Draftable API Self-Hosted v3 using Podman as an alternative to Docker. The deployment process is largely identical to Docker, with a few key differences noted below.

Prerequisites

Key Differences

Initial Setup

Proxy Configuration

Configuration

Deployment

Common Commands

Troubleshooting

---

Prerequisites

Software Requirements

Before you begin, ensure you have the following installed on your Linux server:

Component	Requirement
Podman	Version 4.x or later (required for native Compose support)
Docker Compose plugin	Provides the Compose CLI (see Installing Docker Compose Plugin)
Linux distribution	Any distribution that supports Podman (RHEL, CentOS, Rocky Linux, Fedora, Ubuntu, Debian, etc.)

Critical: You must use podman compose (with a space). Do not use podman-compose (with a hyphen) — this is a different tool that is not compatible with this deployment.

Hardware Requirements

Your server should meet the following minimum requirements:

Component	Minimum Requirement
Processor	4 cores running at 2.5 GHz (Intel Xeon 8000 series or better)
Memory	8 GB RAM
Storage	20 GB free disk space

Container Images

Draftable API Self-Hosted v3 uses the following container images from Docker Hub (public, no authentication required):

Image	Purpose
draftable/apish	Main application orchestrator
draftable/apish-web	Django web application and API endpoints
draftable/apish-compare	Document comparison engine
draftable/apish-converter	Office-to-PDF document conversion
draftable/apish-load-balancer	Load balancer and SSL termination

---

Key Differences from Docker

If you’re familiar with the Docker deployment guide, here are the key differences when using Podman:

Aspect	Docker	Podman
Compose command	docker compose	podman compose
Daemon	Requires Docker daemon	Uses Podman socket (daemonless)
Compose installation	Included with Docker Desktop / plugin	Requires Docker Compose plugin (docker-compose-plugin)
Minimum version	Docker 20.10+	Podman 4.x+
Rootless support	Requires configuration	Native support
TLS certificates	Can be injected or via .env	Managed via .env only

Good news: The same docker-compose.yaml file works with Podman Compose without modification.

---

Initial Setup

Verifying Podman Version

Podman 4.x or later is required for native Compose support. Check your version:

podman --version

If you’re running a version below 4.x, you’ll need to upgrade Podman before proceeding.

Installing Docker Compose Plugin

Podman uses the Docker Compose v2 specification. You need to install the Docker Compose CLI plugin (not podman-compose).

On RHEL 8 / RHEL 9 / Rocky Linux / AlmaLinux:

sudo dnf install -y docker-compose-plugin

This installs the Compose CLI to /usr/libexec/docker/cli-plugins/docker-compose.

On Fedora:

sudo dnf install -y docker-compose-plugin

On Ubuntu / Debian:

sudo apt-get update
sudo apt-get install -y docker-compose-plugin

Verify Installation

After installation, verify that podman compose works correctly:

podman compose version

You should see version information for Docker Compose.

Why this approach?

• ✅ No Docker daemon required
• ✅ No Python-based tools needed
• ✅ Fully supported going forward by the Podman project

Do not use podman-compose: The hyphenated podman-compose tool is a separate Python-based implementation that is not compatible with this deployment. You must use podman compose (with a space) which uses the Docker Compose plugin.

Alternative: Using docker compose Command

On some systems, you can also use the docker compose command directly. Podman transparently intercepts Docker commands when Docker is not running.

docker compose up -d
docker compose down

To verify that Podman is handling Docker commands:

docker info

If the output shows Server: Podman, you’re good to go.

Upgrading Podman (if needed)

If your Podman version is below 4.x, upgrade using the following instructions:

RHEL 8

sudo dnf module reset -y container-tools
sudo dnf module enable -y container-tools:rhel8
sudo dnf install -y podman

RHEL 9 / Rocky Linux 9 / AlmaLinux 9

Podman 4.x is included by default:

sudo dnf install -y podman

Fedora

sudo dnf upgrade -y podman

After upgrading, verify your version:

podman --version

Configuring Proxy for Image Downloads (Corporate Environments)

Many corporate environments require all internet traffic to go through a proxy server. If your organization uses a proxy, you’ll need to configure Podman to pull container images through it.

Option 1: Environment Variables

Set proxy environment variables before running Podman commands:

export HTTP_PROXY="http://proxy.yourcompany.com:8080"
export HTTPS_PROXY="http://proxy.yourcompany.com:8080"
export NO_PROXY="localhost,127.0.0.1,.yourcompany.com"

To make these permanent, add them to your shell profile (~/.bashrc or ~/.bash_profile).

Option 2: Podman Configuration File

Create or edit the Podman configuration file at ~/.config/containers/containers.conf (for rootless) or /etc/containers/containers.conf (for rootful):

[engine]
env = [
    "HTTP_PROXY=http://proxy.yourcompany.com:8080",
    "HTTPS_PROXY=http://proxy.yourcompany.com:8080",
    "NO_PROXY=localhost,127.0.0.1,.yourcompany.com"
]

Option 3: Systemd Service Override (Rootful Podman)

For system-wide configuration when running Podman as root:

sudo mkdir -p /etc/systemd/system/podman.service.d
sudo tee /etc/systemd/system/podman.service.d/proxy.conf << EOF
[Service]
Environment="HTTP_PROXY=http://proxy.yourcompany.com:8080"
Environment="HTTPS_PROXY=http://proxy.yourcompany.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1,.yourcompany.com"
EOF

sudo systemctl daemon-reload
sudo systemctl restart podman

Verify Proxy Configuration

Test that Podman can pull images through your proxy:

podman pull docker.io/draftable/apish-web:latest

Replace proxy.yourcompany.com:8080 with your organization’s actual proxy address and port. Contact your IT department if you’re unsure of the correct proxy settings.

Enabling the Podman Socket

Podman Compose requires the Podman socket to be running. Enable and start it with the following commands:

# Check the current status
sudo systemctl status podman.socket

# Enable and start the socket
sudo systemctl enable --now podman.socket

# Verify the socket exists
ls -la /run/podman/podman.sock

You should see the socket file at /run/podman/podman.sock.

Rootless Podman Configuration

Podman supports rootless operation, which is recommended for security. The Draftable containers are built to run as user draftable with UID 1001 and GID 1001.

If you’re running Podman in rootless mode, ensure your security context is configured correctly:

securityContext:
  fsGroup: 1001
  runAsUser: 1001
  runAsGroup: 1001
  runAsNonRoot: true
  seccompProfile:
    type: RuntimeDefault

---

Configuration

Configuration Files

Download the Docker Compose file and sample .env configuration file from our GitHub repository:

https://github.com/draftable/apish

Environment Variables

Create a .env file in your deployment directory with the following key settings:

Server Configuration

# Your domain name (required)
SERVER_DNS=draftable.yourcompany.com

# Allowed hosts - defaults to SERVER_DNS if not specified
# ALLOWED_HOSTS=draftable.yourcompany.com

ALLOWED_HOSTS automatically defaults to the value of SERVER_DNS if not explicitly set.

TLS Certificate Configuration

TLS certificates are managed directly in the .env file. Paste the full certificate and key content:

TLS_CERT="-----BEGIN CERTIFICATE-----
MIIF1jCCBL6gAwIBAgIQBasJMWS3FUHAkicIFBDEezANBgkqhkiG9w0BAQsFADA8
...
-----END CERTIFICATE-----"

TLS_KEY="-----BEGIN PRIVATE KEY-----
MIIEvAIBADANBgkqhkas9w0BAQEFAASCBKYwggSiAgEAAoIBAQCwkdBnnBCdNh9K
...
-----END PRIVATE KEY-----"

Unlike some Docker deployments where certificates are injected into the container filesystem, Podman deployments manage certificates entirely through the .env file.

Product Key

DRAFTABLE_PRODUCT_KEY=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX

Django Secret Key

# Generate a random 64+ character string
DJANGO_SECRET_KEY=your-64-character-random-string-here-make-it-long-and-random

For a complete list of all available environment variables, see the Docker Compose Guide.

---

Deployment

Step-by-Step Deployment

1. Prepare your directory

   Create a dedicated folder containing your .env file and the Docker Compose file:

   mkdir -p /opt/draftable
   cd /opt/draftable
   

   Copy your docker-compose.yaml and .env files to this directory.

2. Verify Podman socket is running

   Ensure the Podman socket is active before proceeding:

   sudo systemctl status podman.socket
   

   If not running, enable it:

   sudo systemctl enable --now podman.socket
   
3. Deploy the containers

   Navigate to your deployment directory and start the services:

   cd /opt/draftable
   podman compose up
   

   To run in the background (detached mode):

   podman compose up -d
   
4. Verify deployment

   Check that all containers are running:

   podman compose ps
   

   You should see all services in a “running” state.

5. Access the web interface

   Open your browser and navigate to the HTTPS address configured in your .env file:

   https://draftable.yourcompany.com
   
6. Complete initial setup

   On first launch, you’ll be prompted to:

   1. Create an Administrator account
   2. Log in with your new credentials
   3. Retrieve your API credentials from Account Settings

   For detailed instructions on the initial setup wizard, see the Quick Start Guide.

---

Common Podman Commands

Here are the Podman equivalents of common Docker Compose commands:

Starting and Stopping

Action	Command
Start services (foreground)	podman compose up
Start services (background)	podman compose up -d
Stop services	podman compose down
Restart services	podman compose restart
Stop without removing containers	podman compose stop

Viewing Logs

Action	Command
View all logs	podman compose logs
View logs for specific service	podman compose logs web
Follow logs in real-time	podman compose logs -f
View last 100 lines	podman compose logs --tail=100

Container Management

Action	Command
List running containers	podman compose ps
List all containers	podman compose ps -a
Execute command in container	podman compose exec web bash
Pull latest images	podman compose pull

Updating Draftable

To update to the latest version:

# Stop the current deployment
podman compose down

# Pull the latest images
podman compose pull

# Start with new images
podman compose up -d

---

Troubleshooting

Podman Socket Not Running

Symptom: podman compose commands fail with connection errors.

Solution: Enable and start the Podman socket:

sudo systemctl enable --now podman.socket
ls -la /run/podman/podman.sock

---

Permission Denied on Volumes

Symptom: Containers fail to start with permission errors when accessing mounted volumes.

Possible causes:

1. Rootless mode UID mismatch: The container expects UID/GID 1001
2. SELinux restrictions (on RHEL-based systems)

Solutions:

For UID/GID issues, ensure your security context uses the correct user:

securityContext:
  runAsUser: 1001
  runAsGroup: 1001
  fsGroup: 1001

SELinux Note: On RHEL-based systems (RHEL, CentOS, Rocky Linux, AlmaLinux, Fedora), SELinux is enabled by default and may block container access to mounted host directories. If you encounter volume permission issues:

1. Check if SELinux is enforcing: getenforce
2. Try adding the :z or :Z suffix to volume mounts in your compose file
3. Or configure appropriate SELinux policies for your deployment

Example volume mount with SELinux label:

volumes:
  - ./data:/srv/draftable/data:z

---

Wrong Compose Command

Symptom: Commands fail, behave unexpectedly, or containers don’t work properly.

Cause: Using podman-compose (hyphenated) instead of podman compose (with a space).

Solution:

1. Do not use podman-compose — this is a different tool that is not compatible with this deployment
2. Ensure you have the Docker Compose plugin installed (see Installing Docker Compose Plugin)
3. Always use podman compose (with a space):

# Correct - uses Docker Compose plugin
podman compose up

# WRONG - do not use this
podman-compose up

If podman compose is not recognized, verify:

• Podman version is 4.x or later: podman --version
• Docker Compose plugin is installed: podman compose version

Alternative: You can also use docker compose if Podman is intercepting Docker commands:

docker compose up -d

Verify Podman is handling it by running docker info — it should show Server: Podman.

---

Container Images Not Pulling

Symptom: Podman cannot find or pull the Draftable images.

Solution: Podman may default to a different registry. Explicitly specify Docker Hub:

podman pull docker.io/draftable/apish-web:latest

Or configure Podman to search Docker Hub by editing /etc/containers/registries.conf:

[registries.search]
registries = ['docker.io']

---

Viewing Container Logs

To diagnose issues, check the logs for specific services:

# View all logs
podman compose logs

# View logs for a specific service
podman compose logs web
podman compose logs compare
podman compose logs converter

# Follow logs in real-time
podman compose logs -f web

---

Support

If you encounter issues during deployment, please contact us at [e-mail] with:

• Output of podman compose ps
• Relevant container logs (podman compose logs)
• Your .env file (with sensitive values redacted)
• Output of podman version
• Your Linux distribution and version