Deploy with Podman

API7 Gateway can run its packaged single-host deployment on Podman without Docker Engine. This procedure prepares Podman on Red Hat Enterprise Linux (RHEL), starts the control plane and gateway, verifies an API request, and confirms recovery after a host restart.

API7 Gateway supports this deployment from version 3.10.10 in both rootless and rootful modes. Version 3.10.9 and earlier are not supported. The deployment uses the podman-docker compatibility layer with Docker Compose; podman-compose cannot be substituted for Docker Compose.

The procedure covers an internet-connected host where the control plane and gateway run together. Use Kubernetes when you need native rescheduling, rolling updates, or autoscaling.

Prerequisites

Prepare the following before installing API7 Gateway:

• A RHEL 9.8 host registered with repositories that provide Podman, plus permission to install RPM packages and manage the required systemd services.
• cURL, jq, tar, and OpenSSL.
• Network access to run.api7.ai, Docker Hub, and the upstream service you will configure.
• Available host ports 4321, 7080, 7443, 7900, 7943, 9080, and 9443, plus loopback port 16686.
• A browser that can reach port 7443 on the host.
• A valid API7 Enterprise license. Request a trial license.

Choose one Podman mode and use it consistently for installation and operations. Rootless and rootful Podman use separate image, container, and volume stores.

Prepare Rootless Podman

Run the rootless procedure as the regular user that will own and operate the deployment. Sign in through SSH or the console so systemd creates a user session. Running su or sudo -i to become that user does not create the session required by systemctl --user.

Install Podman, its Docker compatibility layer, and Docker Compose:

sudo dnf install -y dnf-plugins-core podman podman-docker
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
sudo dnf install -y --setopt=install_weak_deps=False docker-compose-plugin

Enable the rootless Podman API socket, keep the user's services running after logout, and restore containers after a host restart:

systemctl --user enable --now podman.socket
sudo loginctl enable-linger "$USER"
systemctl --user enable podman-restart.service

Verify Docker Compose and the recovery settings:

docker compose version
systemctl --user is-active podman.socket
loginctl show-user "$USER" -p Linger
systemctl --user is-enabled podman-restart.service

The commands should print a Docker Compose version, an active socket, Linger=yes, and an enabled restart service.

Prepare Rootful Podman

For rootful operation, open a root shell and keep all subsequent installation and lifecycle commands in that shell:

sudo -i

Install Podman, its Docker compatibility layer, and Docker Compose:

dnf install -y dnf-plugins-core podman podman-docker
dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
dnf install -y --setopt=install_weak_deps=False docker-compose-plugin

Enable the system Podman API socket and container recovery service:

systemctl enable --now podman.socket
systemctl enable podman-restart.service

Verify Docker Compose and the recovery services:

docker compose version
systemctl is-active podman.socket
systemctl is-enabled podman-restart.service

The commands should print a Docker Compose version, an active socket, and an enabled restart service. Rootful operation does not require user lingering.

Install API7 Gateway

Run the Quickstart from a directory that does not already contain an api7-ee directory:

mkdir -p ~/api7
cd ~/api7

curl -fsSL "https://run.api7.ai/api7/quickstart" -o api7-quickstart.sh &&
  bash api7-quickstart.sh

Keep the generated directory named api7-ee. The Compose project and the gateway's connection to the control-plane network use that name.

The Quickstart downloads the current deployment package, starts the control-plane services, and creates a gateway instance in the default gateway group. The gateway joins the package's Compose network automatically and connects to DP Manager at https://dp-manager:7943; no Podman-specific Compose override is required.

Enter the installation directory and verify the services and gateway restart policy:

cd ~/api7/api7-ee

docker compose ps
docker ps --filter "name=api7-ee-gateway-1"
docker inspect api7-ee-gateway-1 \
  --format '{{.HostConfig.RestartPolicy.Name}}'

The Compose services and api7-ee-gateway-1 should be running, and the restart policy should be always.

Check the Dashboard and gateway endpoints:

curl -k -I "https://127.0.0.1:7443/"
curl -i "http://127.0.0.1:9080/"

The Dashboard should return a successful HTTP response. The gateway should return 404 Not Found until you create a route.

If the Quickstart fails, it exits with a nonzero status and prints the service state and recent logs. Correct the reported problem before continuing. A failed service can remain in a restart loop. If the api7-ee directory was created, stop the complete stack before retrying:

cd ~/api7/api7-ee
bash run.sh down

Activate API7 Gateway and Verify Traffic

Open https://<host-address>:7443/, sign in with admin / admin, and upload your API7 Enterprise license.

Continue with Create a Service and Route, then Verify the Proxy. The Quickstart has already created the default gateway group and its gateway instance, so begin with the license activation and API configuration rather than running its Docker installation step.

Do not continue until a request through http://127.0.0.1:9080 returns the expected upstream response.

Verify Recovery After a Host Restart

Restart the host after the first request succeeds. In rootless mode, run:

sudo systemctl reboot

In rootful mode, run systemctl reboot from the root shell. After the host returns, sign in as the user that owns the deployment. Reopen a root shell for a rootful deployment. Do not start any container manually.

Wait for the route you created in the Quick Start to serve traffic again:

cd ~/api7/api7-ee

curl -fsS --max-time 3 --retry 30 --retry-delay 2 --retry-all-errors \
  -o /dev/null "http://127.0.0.1:9080/anything/hello" &&
  echo "API request recovered"

If the request still fails after the retries, inspect docker ps -a, docker compose logs --tail=100, and docker logs --tail=100 api7-ee-gateway-1 before starting anything manually.

Confirm that the containers recovered and retained their restart policies:

docker ps --format '{{.Names}} | {{.Status}}'
docker inspect api7-ee-gateway-1 \
  --format '{{.HostConfig.RestartPolicy.Name}}'

Open the Dashboard and confirm that the default gateway group reports one healthy gateway instance. Send the request again and confirm that the license, service, and route created before the restart remain available.

Podman starts containers after a reboot without applying Compose dependency order. The Dashboard or gateway can restart while PostgreSQL or DP Manager becomes ready, then recover through the always restart policy. Investigate only if the gateway does not become healthy or traffic does not recover.

Manage the Deployment

Run control-plane commands from the api7-ee directory. Follow the Compose-service logs with:

docker compose logs -f

Follow gateway logs separately because the gateway runs outside the Compose project:

docker logs -f api7-ee-gateway-1

Stop the gateway before the Compose services:

docker stop api7-ee-gateway-1
docker compose stop

Restart the Compose services and wait for DP Manager before restarting the gateway:

docker compose start
curl -fsS --max-time 3 --retry 30 --retry-delay 2 --retry-all-errors \
  "http://127.0.0.1:7900/version" > /dev/null &&
  docker start api7-ee-gateway-1

If DP Manager does not become ready after the retries, inspect the Compose service state and logs before starting the gateway.

If you remove the gateway after changing the default admin password, run.sh can no longer use admin:admin to create its replacement. Use Add Gateway Instance in the Dashboard, set the DP Manager address to https://dp-manager:7943, and add --network=api7-ee_api7 to the generated Docker command.

PostgreSQL and Prometheus data remain under the api7-ee directory after the containers stop. Do not delete the directory while you need the deployment data.

Remove the Deployment

caution

The following commands permanently delete the API7 Gateway configuration, PostgreSQL data, Prometheus data, and gateway identity stored under api7-ee.

For a rootless deployment, remove the containers and volumes before deleting the installation directory through the Podman user namespace:

cd ~/api7/api7-ee &&
docker rm -f -t 5 api7-ee-gateway-1 &&
docker compose --profile portal down -v &&
cd .. &&
podman unshare rm -rf ./api7-ee

For a rootful deployment, run the equivalent cleanup from the root shell:

cd ~/api7/api7-ee &&
docker rm -f -t 5 api7-ee-gateway-1 &&
docker compose --profile portal down -v &&
cd .. &&
rm -rf ./api7-ee

The chained commands stop before deleting the directory if gateway removal or Compose cleanup fails.

Compatibility

API7 Gateway supports this procedure from version 3.10.10. The platform combination below is known to work. Because the installation commands use current repository packages, the installed versions may differ from those shown.

Component	Known-compatible version or setting
API7 Gateway	3.10.10
Operating system	RHEL 9.8 on linux/amd64
Podman and podman-docker	5.8.2-8.el9_8
Docker Compose	5.7.0 from docker-compose-plugin-5.7.0-1.el9
Podman modes	Rootless and rootful
SELinux	Enforcing

Deployment Boundaries

This API7 Gateway Podman deployment has the following boundaries:

• This procedure covers the online Quickstart with the control plane and gateway on one RHEL host. It does not cover the offline package, manual Compose deployment, a gateway on another host, remote clients, firewalld rules, or gateway HTTPS traffic on port 9443.
• In both Podman modes, same-host requests on the default Compose network can be recorded with a Podman bridge or container address instead of the original client address. Remote clients were not tested. Validate features that depend on the client IP from the network topology you will operate.
• On rootless RHEL hosts where CPU control is not delegated to the user, Podman's --cpus option is unavailable. This procedure does not configure CPU limits.

Next Steps

Review the Production Deployment Checklist before using a single-host deployment for production traffic.

API7 Gateway Podman deployments follow the same upgrade procedures as Docker Compose deployments. Preserve the installation directory and database backup, then follow the applicable Upgrade Guide.