API Self-Hosted v3 – Podman Deployment Guide

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/tree/v3

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

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.

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

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

Verify deployment

Check that all containers are running:

podman compose ps

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

Access the web interface

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

https://draftable.yourcompany.com

Complete initial setup

On first launch, you’ll be prompted to:

Create an Administrator account
Log in with your new credentials
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:

Rootless mode UID mismatch: The container expects UID/GID 1001
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:

Check if SELinux is enforcing: getenforce
Try adding the :z or :Z suffix to volume mounts in your compose file
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:

Do not use podman-compose — this is a different tool that is not compatible with this deployment
Ensure you have the Docker Compose plugin installed (see Installing Docker Compose Plugin)
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 support@draftable.com 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

Getting Started

Configuration

Deployment Guides

Migration

Instance Management

Prerequisites

Key Differences

Initial Setup

Proxy Configuration

Configuration

Deployment

Common Commands

Troubleshooting

​Prerequisites

​Software Requirements

​Hardware Requirements

​Container Images

​Key Differences from Docker

​Initial Setup

​Verifying Podman Version

​Installing Docker Compose Plugin

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

​On Fedora:

​On Ubuntu / Debian:

​Verify Installation

​Alternative: Using docker compose Command

​Upgrading Podman (if needed)

​RHEL 8

​RHEL 9 / Rocky Linux 9 / AlmaLinux 9

​Fedora

​Configuring Proxy for Image Downloads (Corporate Environments)

​Option 1: Environment Variables

​Option 2: Podman Configuration File

​Option 3: Systemd Service Override (Rootful Podman)

​Verify Proxy Configuration

​Enabling the Podman Socket

​Rootless Podman Configuration

​Configuration

​Configuration Files

https://github.com/draftable/apish/tree/v3

​Environment Variables

​Server Configuration

​TLS Certificate Configuration

​Product Key

​Django Secret Key

​Deployment

​Step-by-Step Deployment

​Common Podman Commands

​Starting and Stopping

​Viewing Logs

​Container Management

​Updating Draftable

​Troubleshooting

​Podman Socket Not Running

​Permission Denied on Volumes

​Wrong Compose Command

​Container Images Not Pulling

​Viewing Container Logs

​Support

Prerequisites

Software Requirements

Hardware Requirements

Container Images

Key Differences from Docker

Initial Setup

Verifying Podman Version

Installing Docker Compose Plugin

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

On Fedora:

On Ubuntu / Debian:

Verify Installation

Alternative: Using `docker compose` Command

Upgrading Podman (if needed)

RHEL 8

RHEL 9 / Rocky Linux 9 / AlmaLinux 9

Fedora

Configuring Proxy for Image Downloads (Corporate Environments)

Option 1: Environment Variables

Option 2: Podman Configuration File

Option 3: Systemd Service Override (Rootful Podman)

Verify Proxy Configuration

Enabling the Podman Socket

Rootless Podman Configuration

Configuration

Configuration Files

Environment Variables

Server Configuration

TLS Certificate Configuration

Product Key

Django Secret Key

Deployment

Step-by-Step Deployment

Common Podman Commands

Starting and Stopping

Viewing Logs

Container Management

Updating Draftable

Troubleshooting

Podman Socket Not Running

Permission Denied on Volumes

Wrong Compose Command

Container Images Not Pulling

Viewing Container Logs

Support