A containerized version of ocserv (OpenConnect VPN server), built from source for security, flexibility, and minimal overhead. This project provides an easy-to-deploy VPN server with support for port forwarding to VPN clients, basic NAT out of the box, and optional Prometheus metrics export via ocserv-exporter for real-time monitoring and alerting.

• ✨ Features
• 📁 Project Structure
• 📦 Installation
• ⚙️ Configuration
• 🚀 Running the Container
• 🧭 Roadmap
• 🙋 Contributing
• 💬 Support
• 📜 License
• 📈 Repository Insights

• 🐳 Fully containerized via Docker & Compose
• ✅ Lightweight image built from debian:bookworm-slim
• 📦 Multi-stage Docker build with optimized final image size
• 🔒 Builds latest ocserv v1.3.0 from source with upstream GPG signature verification
• ⚙️ Includes default ocserv.conf for quick setup and customization
• 🔁 Uses s6-overlay for process supervision and service orchestration
• 🌐 Supports dynamic TCP/UDP port forwarding to VPN clients
• 📊 Optional Prometheus metrics export via ocserv-exporter
• 💡 Custom healthcheck script validates both ocserv and ocserv-exporter
• 🧪 Integrated GitHub Actions CI for build and image integrity testing
• 📜 Licensed under GPLv3

ocserv-docker/
├── .github/workflows/
│   └── docker-publish.yml     # CI for Docker image publishing
├── config/
│   └── ocserv.conf            # ocserv default config
├── rootfs/
│   ├── usr/local/bin/         # Scripts (e.g. healthcheck)
│   └── etc/s6-overlay/        # s6 service definitions
├── .dockerignore              # Files to exclude from Docker build
├── .env                       # Environment variables for Compose
├── docker-compose.yml         # Local dev/test setup
├── Dockerfile                 # Docker image build instructions
├── LICENSE                    # Project license (GPLv3)
├── Makefile                   # Build commands
└── README.md                  # Project documentation

curl -sSL https://get.docker.com | sh

git clone https://github.com/gifi71/ocserv-docker.git /opt/ocserv-docker
cd /opt/ocserv-docker

Customize it to fit your network and authentication setup. The default config is located at:

config/ocserv.conf

Important:

⚠️ Make sure the following setting is present and enabled in your ocserv.conf:

use-occtl = true

This setting enables the occtl command interface, which is required for the custom healthcheck script to verify ocserv status and for the ocserv-exporter to collect Prometheus metrics. Without it, both health monitoring and metrics export will not function correctly.

Example:

PORTS="80:10.10.0.2:80 25565:10.10.0.3:25565"
EXPORTER_ENABLED=1
EXPORTER_INTERVAL=30s
EXPORTER_BIND=0.0.0.0:8000

This will forward traffic on ports 80 and 25565 from the container to the specified VPN clients and serve prometheus metric (see ocserv-exporter for details) at http://0.0.0.0:8000/metrics.

You can customize basic settings without breaking functionality, such as:

• Ports: Change or add host ports to avoid conflicts or expose different VPN ports.
• Volumes: Modify the config folder path if your ocserv.conf or other files are stored elsewhere.
• Container name: Rename the container if you run multiple instances.
• Logging options: Adjust log file size or rotation limits if needed.

To improve TCP performance, especially when using TCP VPN connections, you can enable the following settings by editing /etc/sysctl.conf:

net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr

Apply the changes with:

sysctl -p

These settings optimize packet scheduling and enable the BBR TCP congestion control algorithm, which can significantly enhance TCP throughput and reduce latency. This optimization is particularly useful if your VPN clients mainly use TCP connections.

Start the VPN server:

docker compose up -d

View container logs:

docker compose logs -f ocserv

You can also run the container directly with docker run:

docker run -d \
  --name ocserv \
  --restart unless-stopped \
  --cap-add=NET_ADMIN \
  --device /dev/net/tun:/dev/net/tun \
  --sysctl net.ipv4.ip_forward=1 \
  -p 443:443/tcp \
  -p 443:443/udp \
  --env-file .env \
  -v "$(pwd)/config:/etc/ocserv" \
  --security-opt no-new-privileges \
  ghcr.io/gifi71/ocserv-docker:latest

You can build the Docker image locally using the provided Makefile target:

make oci-image

This runs:

docker buildx build --progress=plain --pull -t ghcr.io/gifi71/ocserv-docker:latest .

which builds the image with detailed output and tags it with ghcr.io/gifi71/ocserv-docker:latest.

• Multi-stage build (430MB -> 113MB)
• Published to GHCR
• s6-overlay supervision
• ocserv-exporter integration
• Extended healthcheck
• CI tests for image validation

Contributions, issues and feature requests are welcome!
Feel free to check the issues page or submit a pull request.

If you find this project useful, feel free to star it 🌟 and share it.
For questions or help, open an issue.

This project includes ocserv, licensed under GNU GPLv3. All derivative works must also be distributed under GPLv3.