🛡️ ocserv-docker

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.

---

📚 Table of Contents

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

---

✨ Features

• 🐳 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

---

📁 Project Structure

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

---

📦 Installation

1. Install Docker

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

2. Clone the Repository

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

---

⚙️ Configuration

3. Edit ocserv Configuration

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.

4. Edit .env (optional, all values can be commented out)

Variable	Description	Default
PORTS	Space-separated list of port forwards in <host>:<client>:<port>	Not set
EXPORTER_ENABLED	Enable ocserv-exporter for Prometheus metrics	0
EXPORTER_INTERVAL	Scrape interval for exporter	30s
EXPORTER_BIND	Exporter listen address	0.0.0.0:8000

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.

5. Edit docker-compose.yml (optional)

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.

6. Optimize Host Networking (optional)

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.

---

🚀 Running the Container

Using Docker Compose

Start the VPN server:

docker compose up -d

View container logs:

docker compose logs -f ocserv

Without Docker Compose

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

Building the Image Yourself

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.

---

🧭 Roadmap

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

---

🙋 Contributing

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

---

💬 Support

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

---

📜 License

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

---

📈 Repository Insights