Skip to content
Tutorials Center
My learning

Topics

Lesson 91 of 111 ยท Language Recipes

Running Dev Tools in Containers: Jenkins, Gitea, Portainer, Pi-hole

Run Jenkins, Gitea, Portainer and Pi-hole in Docker: volumes for state, ports, the Docker socket risk, a custom Jenkins image with plugins and a DNS container.

Containers are not only for your own code. Many popular tools ship as official images, and running them in Docker is the fastest way to try them or to host them for a team: a CI server, a Git host, a container dashboard, a network-wide ad blocker. All of them follow the same recipe: one image, one volume for state, a few published ports, and a few settings in environment variables.

This lesson walks through four tools that show four different patterns: Jenkins (a custom image with plugins), Gitea (a tiny, self-contained service), Portainer (a container that controls Docker itself, and the risk that brings), and Pi-hole (a container that serves DNS). Each was started and tested on Docker 29 with throwaway names, volumes and 127.0.0.1 ports, then removed. Version numbers change quickly, so check each project's docs for the current image tag.

The recipe all four share

Before the specifics, notice the habits that make self-hosted containers safe to operate:

  • State in a named volume. The container is replaceable, the data is not (Volumes). If you can docker rm the container and lose nothing, you can also upgrade by pulling a new tag.
  • Publish only what you need, and bind to localhost while experimenting: -p 127.0.0.1:3000:3000. Put a reverse proxy with HTTPS in front before exposing a tool to a network (Multiple Apps Behind a Proxy, Port Publishing).
  • Pin tags. latest moves. For anything you keep, use a specific version tag (Image Tagging Strategy).
  • Configuration through environment variables where the image supports it, files in the volume otherwise (Environment Config).
  • Back up the volume (Backup and Restore).

Gitea: a self-hosted Git server

Gitea is a lightweight Git hosting service (repositories, issues, pull requests, a package registry, CI actions). It is one Go binary, so the container is small, and it can use SQLite for its database.

Terminal
docker volume create gitea-data
docker run -d --name gitea \
  -p 127.0.0.1:3000:3000 \
  -v gitea-data:/data \
  -e GITEA__database__DB_TYPE=sqlite3 \
  -e GITEA__server__ROOT_URL=http://localhost:3000/ \
  gitea/gitea:latest

Environment variables named GITEA__section__KEY map onto the app.ini configuration file, so GITEA__database__DB_TYPE sets DB_TYPE in the [database] section. The image exposes ports 3000 (web) and 22 (SSH for git clone over SSH). Everything it stores, including the database, repositories and configuration, lives under /data, which is why one volume is enough:

TEXT
$ docker exec gitea ls /data
git  gitea  ssh

The first request to http://localhost:3000 opens an installation page. To skip it for automation, add -e GITEA__security__INSTALL_LOCK=true and create the first admin from the command line (run it as the git user, not root):

Terminal
docker exec -u git gitea gitea admin user create \
  --admin --username demo --password 'choose-a-real-one' --email [email protected]

Gitea reports its health at /api/healthz, a good target for a Compose healthcheck:

TEXT
$ curl -s http://127.0.0.1:3000/api/healthz
{ "status": "pass", "description": "Gitea: Git with a cup of tea", ... }

To prove that the volume holds the state, remove the container and start a new one with the same volume. The user, repositories and settings are still there, and a git push to http://localhost:3000/demo/hello.git works as before. For more than a few users, switch the database to PostgreSQL in a second container (Databases in Containers).

Jenkins: a custom image with plugins

Jenkins is a long-running CI server. Its official image is large (it bundles a JDK), and almost all of its features come from plugins, so the usual pattern is to build your own image from the official one and install plugins at build time. Plugins installed this way are part of the image, so every container starts identical.

DOCKERFILE
FROM jenkins/jenkins:lts-jdk21
ENV JAVA_OPTS="-Djenkins.install.runSetupWizard=false"
RUN jenkins-plugin-cli --plugins git:latest

jenkins-plugin-cli is included in the base image. It resolves a plugin and all of its dependencies and downloads them into /usr/share/jenkins/ref/plugins; building this image put 25 plugin files there (the Git plugin plus its dependencies). For repeatable builds, list plugins with exact versions in a plugins.txt file and use jenkins-plugin-cli -f plugins.txt. Setting runSetupWizard=false skips the "install suggested plugins" wizard; combine it with Jenkins Configuration as Code to configure users and jobs from a YAML file.

Run it with a volume for JENKINS_HOME, where jobs, credentials and build history live:

Terminal
docker volume create jenkins-home
docker run -d --name jenkins \
  -p 127.0.0.1:8080:8080 \
  -v jenkins-home:/var/jenkins_home \
  jenkins/jenkins:lts-jdk21

The container runs as the unprivileged user jenkins (uid 1000). When the setup wizard is on, the first admin password is in the log and in a file:

TEXT
$ docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

Port 8080 serves the web UI; agents connect on 50000 if you use inbound agents (publish it only when you do). Memory is the tuning knob: pass -e JAVA_OPTS="-Xmx1g" or set a container memory limit (Resource Limits) so builds cannot starve the host.

Building images from Jenkins is where the Docker socket comes in, and where people get hurt. The next section explains the risk. The safer choices are build agents in separate containers or VMs, or daemonless builders such as BuildKit in rootless mode (Docker in Docker, CI Pipelines).

Portainer and the Docker socket

Portainer is a web dashboard for Docker: it lists containers, images, volumes and networks, shows logs, opens shells and deploys Compose stacks. It manages Docker by talking to the Docker API, and the standard way to give it access is to mount the Docker socket:

Terminal
docker volume create portainer-data
docker run -d --name portainer \
  -p 127.0.0.1:9000:9000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v portainer-data:/data \
  portainer/portainer-ce:latest

On startup the container answers on the status endpoint, and its own data (a small database and generated certificate) lands in /data:

TEXT
$ curl -s http://127.0.0.1:9000/api/system/status
{"Version":"2.45.3","InstanceID":"..."}

The first visit asks you to create an admin user within a few minutes; if the window passes, restart the container.

Why mounting the socket is dangerous

/var/run/docker.sock is the daemon's API. Anything that can write to it can ask the daemon to do anything, and the daemon runs as root on the host. Here is the proof, using a throwaway container that mounts the socket read-only and talks to the API with curl:

Terminal
docker run --rm --user root -v /var/run/docker.sock:/var/run/docker.sock:ro \
  curlimages/curl --unix-socket /var/run/docker.sock -sS \
  http://localhost/containers/json

The reply is a JSON list of every container on the host, including this one. The :ro flag only makes the file read-only, not the API behind it, so the same container could also create a new one:

Terminal
docker run --rm --user root -v /var/run/docker.sock:/var/run/docker.sock:ro \
  curlimages/curl --unix-socket /var/run/docker.sock -sS -X POST \
  -H 'Content-Type: application/json' \
  -d '{"Image":"busybox","Cmd":["true"]}' \
  'http://localhost/containers/create?name=made-through-ro-socket'
TEXT
{"Id":"5d87a03082f1...","Warnings":[]}

The container was created. A real attacker would create one that mounts the host's root filesystem with --privileged and read anything. That is why access to the Docker socket is equivalent to root on the host. Note also that the first attempt, without --user root, failed to connect: the socket is owned by root, so a non-root process is refused unless the group is set up. That is a protection, but not a reliable one.

What to do instead:

  • Treat a container with the socket as fully trusted. Never mount it into a service that handles untrusted input or runs untrusted code (CI runners for pull requests from strangers are the classic case).
  • Put the dashboard behind authentication and HTTPS, and never expose its port to the internet.
  • Use a socket proxy that only allows read-only API calls (several community images do this) when a tool just needs to list containers.
  • Use rootless Docker or a remote context with TLS and client certificates for tools that must manage a daemon (Securing the Docker Daemon).

Pi-hole: a DNS server in a container

Pi-hole answers DNS queries for your network and returns a null address for domains on block lists (ads, trackers). Unlike the others, it is a network service on port 53, so the interesting parts are the ports and DNS settings.

Terminal
docker volume create pihole-data
docker run -d --name pihole \
  -p 53:53/udp -p 53:53/tcp \
  -p 127.0.0.1:8081:80/tcp \
  -e TZ=UTC \
  -e FTLCONF_webserver_api_password='choose-a-real-one' \
  -e FTLCONF_dns_upstreams=1.1.1.1 \
  -v pihole-data:/etc/pihole \
  pihole/pihole:latest

(To test on a workstation where something already uses port 53, publish a different host port, for example 127.0.0.1:15353:53/udp and /tcp; the tests for this lesson did exactly that.)

  • Settings use FTLCONF_ variables in the v6 image: the admin password, upstream DNS servers, and so on. Check the image's documentation for names, because they changed between major versions.
  • Port 53 over both UDP and TCP is needed. Port 80 is the admin UI at /admin/.
  • State (block lists, settings, query history) lives in /etc/pihole.

Once it is running, anything can use it as a DNS server. Another container can do that with --dns:

Terminal
docker run --rm --dns 172.17.0.5 busybox nslookup example.com
TEXT
Server:     172.17.0.5
Address:    172.17.0.5:53

Non-authoritative answer:
Name:   example.com
Address: 104.20.23.154

(Use the address from docker inspect pihole.) Block a domain and see the difference:

Terminal
docker exec pihole pihole deny ads.blocked.test
docker exec pihole dig +short @127.0.0.1 ads.blocked.test
TEXT
0.0.0.0

Allowed names are forwarded to the upstream resolver; denied names get 0.0.0.0 (and :: for IPv6). Point your router's DHCP DNS setting at the host and every device in the network benefits. Two practical warnings:

  1. A DNS server is a single point of failure. If the container stops, name resolution stops for everyone using it. Use --restart unless-stopped and consider a second instance (Container Lifecycle).
  2. Never expose port 53 to the internet: open resolvers are abused for traffic amplification attacks. Bind to your LAN address or localhost.

A Compose file for the whole tool shelf

For a home lab or a team server, put them in one file with pinned tags (shown with latest here only for brevity) and one volume per tool:

YAML
services:
  gitea:
    image: gitea/gitea:latest
    ports: ["127.0.0.1:3000:3000"]
    volumes: [gitea-data:/data]
    environment:
      GITEA__database__DB_TYPE: sqlite3
    restart: unless-stopped

  jenkins:
    build: ./jenkins               # the Dockerfile from above
    ports: ["127.0.0.1:8080:8080"]
    volumes: [jenkins-home:/var/jenkins_home]
    restart: unless-stopped

volumes:
  gitea-data:
  jenkins-home:

Portainer is left out on purpose: leave the socket-mounting tool out of a shared file unless you have decided it is worth the risk (Compose Services).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why do these self-hosted tools each get a named volume?

    Containers are disposable. The state (repositories, jobs, settings) belongs in a volume that survives docker rm and image upgrades.
  2. 2. What is the best way to get a fixed set of Jenkins plugins into every container?

    jenkins-plugin-cli, included in the base image, resolves and downloads plugins and their dependencies during the build, so every container starts identical.
  3. 3. A container mounts /var/run/docker.sock with the :ro flag. What can it still do?

    The flag only makes the socket file read-only. The API behind it accepts requests such as container create, so socket access is equivalent to root on the host.
  4. 4. Which publishing choice is right for a Pi-hole you want only your own LAN to use?

    DNS needs port 53 over UDP and TCP, but an open resolver on the public internet is abused for amplification attacks. Bind it to the LAN.

Summary

  • Self-hosted tools follow one recipe: pinned image, one volume for state, localhost-bound ports, config through environment variables, and a backup of the volume.
  • Gitea needs one container and /data; its GITEA__section__KEY variables map to app.ini, and /api/healthz gives a health check.
  • Jenkins is best built as a custom image with jenkins-plugin-cli, with JENKINS_HOME in a volume and a memory limit.
  • Mounting the Docker socket (Portainer, CI jobs) gives root-equivalent power, even with :ro; limit it to trusted tools or use a socket proxy, rootless Docker or a remote TLS context.
  • Pi-hole is a DNS service on port 53 (UDP and TCP) with state in /etc/pihole; keep it off the public internet.

Next: Orchestration Basics shows how to run containers like these across several machines.