This content originally appeared on DEV Community and was authored by Sharon
Having trouble installing or upgrading SafeLine WAF? Whether you’re running into Docker issues, port conflicts, or upgrade compatibility problems, this guide covers the most common pitfalls — and how to fix them.
Common Installation Errors & Fixes
nginx: [emerg] invalid IPv6 address in resolver
Open /etc/resolv.conf and remove any invalid IPv6 resolver lines. Then restart Tengine:
docker restart safeline-tengine
Cannot connect to the Docker daemon at unix:///var/run/docker.sock
This usually means Docker is not installed. Install it with:
curl -fLsS https://get.docker.com/ | sh
Or follow Docker Engine installation docs.
failed to create network safeline-ce
The network safeline-ce is required for SafeLine to function. If creation fails, restart Docker:
systemctl restart docker
docker compose v2 not found
SafeLine requires Docker Compose v2. Follow Docker Compose install instructions.
safeline-tengine: Address already in use
Port conflict detected. Use:
docker logs -f safeline-tengine
Check which port is occupied, then resolve the conflict manually.
Ports used by SafeLine:
-
9443: Admin panel (can be customized) -
65508: Health check (fixed) -
65443: Custom error pages (fixed)
safeline-mgt-api: Operation not permitted
This issue happens with older Docker versions (20.10.9 and below). Upgrade Docker if possible.
Alternatively, if your system supports seccomp (check with:
grep CONFIG_SECCOMP= /boot/config-$(uname -r)), use a custom seccomp profile:
- Download
seccomp.jsoninto the SafeLine install directory. - Edit
compose.yaml, under themanagementservice, add:
security_opt:
- seccomp=./seccomp.json
- Restart containers:
docker compose down && docker compose up -d
safeline-pg: Operation not permitted
Again, this points to an outdated Docker version. Upgrade Docker to resolve.
Pool overlaps with other one on this address space
This is a Docker network conflict. Change the SUBNET_PREFIX in /data/safeline/.env to a unique subnet.
“It does not belong to any of this network’s subnets…”
Try a clean reinstall:
- Uninstall SafeLine as per instructions
- Re-deploy from scratch
Customizing SafeLine
Change the Management Port (default is 9443)
- Check current port usage:
ss -antp | grep LISTEN
- Edit the hidden
.envfile in your SafeLine directory and set:
MGT_PORT=your_custom_port
- Restart:
docker compose down && docker compose up -d
Change Installation Path
Modify the SAFELINE_DIR variable in your .env file.
Deploying SafeLine and Business Services on the Same Server?
It’s possible — but not recommended. Shared environments increase CPU/memory contention and reduce performance.
macOS / Windows Support?
The Community Edition currently supports only Linux. Contact us if you need Enterprise Edition for other platforms.
Recommended System Requirements
Choose based on your business traffic (QPS = Queries Per Second):
- QPS < 100: 2 CPU cores, 4 GB RAM
- QPS 100–1000: 4 CPU cores, 8 GB RAM
- QPS > 1000: 8+ CPU cores, 16 GB+ RAM
These are baseline recommendations — please benchmark based on your workload.
Upgrade Issues & How to Avoid Them
Compatibility Issues Across Major Versions
When upgrading across multiple major versions, data format changes may prevent the system from starting.
Always backup before a big upgrade.
Ran Upgrade in the Wrong Directory?
You must run upgrades from the installation directory (default: /data/safeline). If you ran it from a subfolder, the upgrade may silently fail.
How to Backup & Restore Configurations
Backup
Copy the entire installation directory (/data/safeline).
Restore
Place it back, then run:
docker compose down && docker compose up -d
Post-upgrade Issues
- API errors or Docker misbehavior? Restart Docker.
- Old settings not working? Manually reconfigure or reset.
Final Tips
- Upgrade Docker regularly.
- Always test changes on a staging server before rolling out.
- Keep backups of
.env,compose.yaml, andseccomp.jsonhandy.
Join the SafeLine Community
This content originally appeared on DEV Community and was authored by Sharon