Installing Portainer with Docker on CentOS 8 – Quick, No‑Nonsense Guide
If you’re running a fresh CentOS 8 box and want a slick web UI to manage your containers, this walk‑through gets you from zero to “Portainer dashboard” in under fifteen minutes. No fluff, just the bits that matter.
Why Docker First – Even on CentOS 8
You might think “CentOS 8 is already a container platform.” That’s only partially true; it ships with Podman, which is great but not what Portainer expects out of the box. Portainer talks to the Docker engine over its REST API, so you need the official Docker CE binaries. Skipping this step means your Portainer install will sit on a dead‑end that can’t talk to containers.
Step 1: Add the Docker Repository
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
The default CentOS repos ship an outdated docker package that won’t play nicely with modern images. By pointing to Docker’s own repo you get the latest stable release and automatic updates via dnf.
Step 2: Install Docker CE (Community Edition)
sudo dnf install -y docker-ce docker-ce-cli containerd.io
The triple package pull pulls in the engine, the CLI you’ll use for debugging, and containerd – the runtime that actually runs your images. If you skip containerd.io, Docker will complain about missing runtime dependencies.
Step 3: Start & Enable Docker
sudo systemctl start docker sudo systemctl enable docker
Without an active service, Docker never listens on the Unix socket. Enabling it ensures the daemon boots with the OS – handy when you’re running services that spin up containers automatically.
Step 4: Verify Docker is Running
sudo docker run --rm hello-world
You should see a “Hello from Docker!” message. If not, check systemctl status docker and look for permission issues. One time I got the same error after a rogue SELinux policy update that blocked /var/lib/docker; resetting the policy cleared it.
Step 5: Pull the Portainer Image
sudo docker pull portainer/portainer-ce:latest
The --latest tag guarantees you get the newest features and bug fixes. If you’re on a bandwidth‑tight machine, consider pulling :stable instead.
Step 6: Create a Docker Volume for Persistent Data
sudo docker volume create portainer_data
Portainer stores its configuration (users, endpoints, etc.) inside this volume. Without it you’d lose all settings every time the container restarts.
Step 7: Run Portainer
sudo docker run -d \ --name=portainer \ -p 9000:9443 \ --restart=always \ -v /var/run/docker.sock:/var/run/docker.sock \ -v portainer_data:/data \ portainer/portainer-ce:latest
| Flag | Why it matters |
|---|---|
| -d | Keeps the container in background, letting you use the shell again. |
| --name=portainer | Gives the container a friendly name; handy when you later run docker stop portainer. |
| -p 9000:9443 | Exposes Portainer’s HTTPS endpoint on port 9000 so you can hit https://:9000 in your browser. If you want HTTP, swap to -p 9000:8000. |
| --restart=always | Makes sure Docker brings Portainer back up after a reboot or crash – the ultimate safety net for an admin UI. |
| -v /var/run/docker.sock:/var/run/docker.sock | Gives Portainer direct access to the Docker daemon; without this it can’t list or manage containers. |
| -v portainer_data:/data | Binds the persistent volume we created, preserving settings across restarts. |
Step 8: Open Portainer in Your Browser
Navigate to https://<your‑server>:9000. The first time you hit it, you’ll be prompted to create an admin user and connect to “Local” (your Docker host). After that you’re ready to drag‑and‑drop containers or run docker exec commands from a handy web console.
Common Gotchas on CentOS 8
- SELinux – If you see “Permission denied” when Portainer tries to read the socket, temporarily set SELinux to permissive (sudo setenforce 0). After confirming it’s an SELinux issue, add a proper boolean: sudo semanage port -a -t http_port_t -p tcp 9000.
- Firewalld – CentOS 8 ships with firewalld enabled. Add the rule: sudo firewall-cmd --permanent --add-port=9000/tcp && sudo firewall-cmd --reload.
Why Portainer is Worth It
You might think “I can just use docker‑compose or kubectl.” That’s fine for seasoned devs, but if you’re a sysadmin who wants a quick visual overview of running containers on multiple hosts, Portainer is the lightweight, open‑source answer. It keeps your Docker installation lean while giving you that extra layer of convenience.
