Deploy AISIX Enterprise with Podman

AISIX Enterprise runs on Podman without Docker Engine, allowing RHEL operators to use Podman for the control plane and a same-host AISIX gateway. Docker Compose orchestrates the services through the podman-docker compatibility layer.

Podman support is available in AISIX Enterprise 1.10.0 and later for both rootless and rootful operation. Use Docker Compose as the Compose provider; podman-compose is not supported.

Running the control plane and gateway together on one internet-connected RHEL host keeps evaluation and non-HA deployments straightforward. The workflow begins with host preparation, continues through installation and a verified AI request, and finishes by checking automatic recovery after a reboot. For control-plane high availability or an external PostgreSQL database, use Helm.

Prerequisites

Prepare the following before installing AISIX Enterprise:

• 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, download.docker.com, Docker Hub, and the model provider you will configure.
• Available host ports 5432, 8080, 7944, and 3000.
• A browser that can reach port 8080 on the host.
• A model-provider API key. The verification steps use OpenAI.

Choose one Podman mode and use it consistently for installation and operations. Rootless mode stores containers and volumes under the selected user's account. Rootful mode stores them under root's Podman storage. The two modes do not share containers, images, or volumes.

Prepare Rootless Podman

For rootless Podman, sign in as the regular user who will own and operate the deployment. Use SSH or the console so systemd creates a real 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.

Deploy the Control Plane

Complete the online installation under Docker Compose on a Host. With podman-docker, Docker Compose, and the Podman socket prepared above, run the Quickstart exactly as shown. After it reports success, return here and enter the installation directory:

cd aisix-self-hosted

Configure the data-plane manager address for a gateway that will join the same Compose network.

The package defaults to http://localhost:8080 for dashboard access. If the browser reaches the dashboard through another origin, first set AISIX_CLOUD_PUBLIC_BASE_URL in .env to that exact origin. See Configure External Access for trusted origins, reverse proxies, and externally reachable endpoints.

The command below recreates api with the configured dashboard origin and recreates dpm with the data-plane manager address:

sed -i \
  's|^AISIX_CLOUD_DPMGR_BASE_URL=.*|AISIX_CLOUD_DPMGR_BASE_URL=https://dpm:7944|' \
  .env

docker compose up -d api dpm

Check the control-plane health endpoint:

curl -fsS --retry 30 --retry-delay 2 --retry-all-errors \
  "http://127.0.0.1:8080/healthz"

The endpoint should return {"status":"ok"}. Check the service state if it does not become healthy after the retries:

docker compose ps
docker compose logs --tail=100 api dpm postgres

Back up .env with the database. It contains the PostgreSQL password and master key required to interpret the stored data, and later package archives do not include it. See Backup and Recovery.

Configure Gateway Resources

Open the configured dashboard URL and sign in with the first administrator credentials. Change the initial password when prompted.

Complete Create an Admin Token and Create Gateway Resources. Keep the exported AISIX_CP, AISIX_TOKEN, ENV_ID, and AISIX_API_KEY values in the same terminal for the verification steps below.

Connect the Gateway

Connect the gateway to the same network as the control-plane services:

1. In the dashboard, open the environment you created and select Data planes.
2. Select Issue certificate, then open the Docker tab.
3. Copy the generated command and add --network aisix-self-hosted_aisix immediately after the docker run line. The command contains the gateway certificate and private key, so handle it as a secret and do not commit or share it.
4. Run the modified command on the Podman host.

The generated command starts a container named aisix-dp with a restart policy and a 45-second stop timeout. It waits for http://127.0.0.1:3000/readyz and returns when the gateway has received its first configuration. The configured https://dpm:7944 endpoint resolves through the shared Compose network.

If the readiness check keeps waiting, inspect the gateway logs from another terminal:

docker logs aisix-dp

Return to Data planes, refresh the page, and confirm that the gateway reports a recent heartbeat.

Send and Verify a Request

Export the local gateway address and check its listeners:

export AISIX_PROXY="http://127.0.0.1:3000"

curl -fsS "$AISIX_PROXY/livez"
curl -fsS "$AISIX_PROXY/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

The first command should return ok. The second response's data array should include the configured model. Configuration changes can take a few seconds to reach the gateway, so retry if the model is not listed yet.

Send a request through the gateway:

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer ${AISIX_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "Say hello from AISIX Enterprise on Podman."}
    ]
  }'

The gateway should return an OpenAI-compatible response with an assistant message under choices[0].message. In the dashboard, use Logs in the environment to inspect the request and Usage in the organization navigation to confirm that its usage data arrived.

Verify Recovery After a Host Restart

Restart the host after the first request succeeds:

sudo systemctl reboot

For rootless operation, sign back in as the user that owns the deployment. For rootful operation, reopen a root shell. Do not start the containers manually.

Confirm that the control plane and gateway recovered:

docker ps --format '{{.Names}} | {{.Status}}'
curl -fsS --retry 30 --retry-delay 1 --retry-all-errors \
  "http://127.0.0.1:8080/healthz"
curl -fsS --retry 30 --retry-delay 1 --retry-all-errors \
  "http://127.0.0.1:3000/readyz"

The containers should be running, the control-plane endpoint should return {"status":"ok"}, and the gateway endpoint should return ok. Send another request and confirm that the previously created environment, model, API key, certificate, and administrator password still work.

After the restart, Data planes can temporarily show the previous gateway instance as warning or offline alongside the healthy recovered instance. The stale entry remains for about one hour and does not indicate that recovery failed. Confirm that the current instance has a recent heartbeat.

After a reboot, cp-api can briefly log the database system is starting up (SQLSTATE 57P03) because Podman starts the containers without applying Compose dependency ordering. Its restart policy should recover it automatically. Investigate only if the health endpoint does not recover.

Manage the Deployment

Run control-plane lifecycle commands from the aisix-self-hosted directory:

./run.sh logs
./run.sh stop

Stop and remove the separately managed gateway before bringing the Compose project down. ./run.sh down then removes the control-plane containers but preserves the PostgreSQL volume:

docker rm -f aisix-dp
./run.sh down

Stopping the gateway can take about 30 seconds while it drains active requests. The generated command allows 45 seconds for graceful shutdown; requests that outlast the timeout can be terminated.

Compatibility

Podman support starts with AISIX Enterprise 1.10.0. The Quickstart installs the current AISIX Enterprise release. RHEL, Podman, and Docker Compose come from the host's package repositories, so their exact versions can vary. Use the configuration below as a reference for a RHEL deployment.

Component	Reference version or setting
AISIX Enterprise	1.10.0
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 Considerations

The setup above uses the online package and runs the control plane and gateway together on one RHEL host. For an offline installation or a Helm-based control plane, start with Deploy the AISIX Enterprise Control Plane. When gateways or clients run on other hosts, plan externally reachable endpoints, firewall rules, and client-address behavior for the target network.

• If a rootless gateway is not attached to the shared Compose network, use 127.0.0.1:3000 instead of localhost:3000. Resolving localhost to the IPv6 loopback address can reset the connection because the gateway listens on IPv4.
• On rootless RHEL hosts where CPU control is not delegated to the user, Podman's --cpus option is unavailable. The commands above leave CPU limits unset.
• Requests from the same host can record a translated Podman network address rather than the original client address. Validate IP-based access controls with clients on the network topology you will operate.
• Add the :Z volume option to operator-added bind mounts on an SELinux host. Without the label adjustment, a container can receive Permission denied even when it runs as root.
• With journald logging on a host without a persistent journal, container logs do not survive a host restart. Plan log retention separately when logs must survive a reboot.

Next Steps

For production planning, review Deploy the AISIX Enterprise Control Plane for resource sizing, external access, high availability, and database options.

Before an upgrade, preserve the matching database, .env, deployment files, and software version as one recovery set. AISIX Enterprise Podman deployments use the same AISIX Enterprise upgrade procedure as Docker Compose deployments.