> ## Documentation Index
> Fetch the complete documentation index at: https://help.draftable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<CardGroup>
  <Card title="Prerequisites" icon="clipboard-check" href="#prerequisites" iconType="solid" horizontal />

  <Card title="Key Differences" icon="arrows-left-right" href="#key-differences-from-docker" iconType="solid" horizontal />

  <Card title="Initial Setup" icon="gear" href="#initial-setup" iconType="solid" horizontal />

  <Card title="Proxy Configuration" icon="building" href="#configuring-proxy-for-image-downloads-corporate-environments" iconType="solid" horizontal />

  <Card title="Configuration" icon="sliders" href="#configuration" iconType="solid" horizontal />

  <Card title="Deployment" icon="rocket" href="#deployment" iconType="solid" horizontal />

  <Card title="Common Commands" icon="terminal" href="#common-podman-commands" iconType="solid" horizontal />

  <Card title="Troubleshooting" icon="wrench" href="#troubleshooting" iconType="solid" horizontal />
</CardGroup>

***

## 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](#installing-docker-compose-plugin)) |
| **Linux distribution**    | Any distribution that supports Podman (RHEL, CentOS, Rocky Linux, Fedora, Ubuntu, Debian, etc.)      |

<Warning>
  **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.
</Warning>

### 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](/hc/en-us/articles/51133475373465-API-Self-Hosted-v3-Quick-Start-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                                  |

<Note>
  **Good news**: The same `docker-compose.yaml` file works with Podman Compose without modification.
</Note>

***

## Initial Setup

### Verifying Podman Version

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

```bash theme={null}
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:

```bash theme={null}
sudo dnf install -y docker-compose-plugin
```

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

#### On Fedora:

```bash theme={null}
sudo dnf install -y docker-compose-plugin
```

#### On Ubuntu / Debian:

```bash theme={null}
sudo apt-get update
sudo apt-get install -y docker-compose-plugin
```

### Verify Installation

After installation, verify that `podman compose` works correctly:

```bash theme={null}
podman compose version
```

You should see version information for Docker Compose.

<Tip>
  **Why this approach?**

  * ✅ No Docker daemon required
  * ✅ No Python-based tools needed
  * ✅ Fully supported going forward by the Podman project
</Tip>

<Warning>
  **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.
</Warning>

### 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.

```bash theme={null}
docker compose up -d
docker compose down
```

To verify that Podman is handling Docker commands:

```bash theme={null}
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

```bash theme={null}
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:

```bash theme={null}
sudo dnf install -y podman
```

#### Fedora

```bash theme={null}
sudo dnf upgrade -y podman
```

After upgrading, verify your version:

```bash theme={null}
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:

```bash theme={null}
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):

```ini theme={null}
[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:

```bash theme={null}
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:

```bash theme={null}
podman pull docker.io/draftable/apish-web:latest
```

<Note>
  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.
</Note>

### Enabling the Podman Socket

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

```bash theme={null}
# 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:

```yaml theme={null}
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:

<Card title="https://github.com/draftable/apish" href="https://github.com/draftable/apish" iconType="solid" icon="github" horizontal />

### Environment Variables

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

#### Server Configuration

```bash theme={null}
# Your domain name (required)
SERVER_DNS=draftable.yourcompany.com

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

<Note>
  `ALLOWED_HOSTS` automatically defaults to the value of `SERVER_DNS` if not explicitly set.
</Note>

#### TLS Certificate Configuration

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

```bash theme={null}
TLS_CERT="-----BEGIN CERTIFICATE-----
MIIF1jCCBL6gAwIBAgIQBasJMWS3FUHAkicIFBDEezANBgkqhkiG9w0BAQsFADA8
...
-----END CERTIFICATE-----"

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

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

#### Product Key

```bash theme={null}
DRAFTABLE_PRODUCT_KEY=XXXXX-XXXXX-XXXXX-XXXXX-XXXXX
```

#### Django Secret Key

```bash theme={null}
# 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](/hc/en-us/articles/51141426113049-Draftable-API-Self-Hosted-v3-Docker-Compose-Guide).

***

## Deployment

### Step-by-Step Deployment

<Steps>
  <Step title="Prepare your directory">
    Create a dedicated folder containing your `.env` file and the Docker Compose file:

    ```bash theme={null}
    mkdir -p /opt/draftable
    cd /opt/draftable
    ```

    Copy your `docker-compose.yaml` and `.env` files to this directory.
  </Step>

  <Step title="Verify Podman socket is running">
    Ensure the Podman socket is active before proceeding:

    ```bash theme={null}
    sudo systemctl status podman.socket
    ```

    If not running, enable it:

    ```bash theme={null}
    sudo systemctl enable --now podman.socket
    ```
  </Step>

  <Step title="Deploy the containers">
    Navigate to your deployment directory and start the services:

    ```bash theme={null}
    cd /opt/draftable
    podman compose up
    ```

    To run in the background (detached mode):

    ```bash theme={null}
    podman compose up -d
    ```
  </Step>

  <Step title="Verify deployment">
    Check that all containers are running:

    ```bash theme={null}
    podman compose ps
    ```

    You should see all services in a "running" state.
  </Step>

  <Step title="Access the web interface">
    Open your browser and navigate to the HTTPS address configured in your `.env` file:

    ```
    https://draftable.yourcompany.com
    ```
  </Step>

  <Step title="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](/hc/en-us/articles/51133475373465-API-Self-Hosted-v3-Quick-Start-Guide#access-the-ui).
  </Step>
</Steps>

***

## 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:

```bash theme={null}
# 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:

```bash theme={null}
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:

```yaml theme={null}
securityContext:
  runAsUser: 1001
  runAsGroup: 1001
  fsGroup: 1001
```

<Note>
  **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:

  ```yaml theme={null}
  volumes:
    - ./data:/srv/draftable/data:z
  ```
</Note>

***

### 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](#installing-docker-compose-plugin))
3. Always use `podman compose` (with a space):

```bash theme={null}
# 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:

```bash theme={null}
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:

```bash theme={null}
podman pull docker.io/draftable/apish-web:latest
```

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

```ini theme={null}
[registries.search]
registries = ['docker.io']
```

***

### Viewing Container Logs

To diagnose issues, check the logs for specific services:

```bash theme={null}
# 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](mailto: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