Installation Issues

Handling Errors During Installation

Error: nginx: [emerg] invalid IPv6 address in resolver

To resolve this, delete the corresponding IPv6 address line in /etc/resolv.conf and then restart SafeLine-Tengine using:

docker restart safeline-tengine

Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

This indicates Docker is not installed. Try installing Docker using:

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

Or follow the instructions to Install Docker Engine.

Error: failed to create network safeline-ce

safeline-ce is the network created during SafeLine deployment. If this error occurs, restart the Docker daemon and try again:

systemctl restart docker

Error: docker compose v2 not found, unable to deploy

Docker Compose v2 needs to be installed. Follow the instructions to Install Docker Compose.

Error: safeline-tengine: Address already in use

If you see Address already in use in the container logs (docker logs -f safeline-tengine), it indicates a port conflict. Identify the conflicting service based on the port number and resolve the conflict manually.

Ports used by SafeLine:

• 9443: Management, customizable (see documentation)
• 65508: Health check, non-customizable
• 65443: Custom page, non-customizable

Error: safelint-mgt-api: Operation not permitted

If you see runtime/cgo: pthread_create failed: Operation not permitted in the container logs (docker logs -f safelint-mgt-api), this usually occurs in Docker 20.10.9 and below.

• The recommended solution is to upgrade Docker to the latest version.
• Alternatively, if your system supports seccomp (check with grep CONFIG_SECCOMP= /boot/config-$(uname -r) and look for CONFIG_SECCOMP=y), download the seccomp profile in the SafeLine working directory, edit the compose.yaml file, add the following under the management section, and restart the containers. Then run:

docker compose down && docker compose up -d

security_opt:
  - seccomp=./seccomp.json

Error: safeline-pg: Operation not permitted

If you see this error in the container logs (docker logs -f safeline-pg), it may be due to an outdated Docker version. Upgrade Docker to the latest version.

Error: Pool overlaps with other one on this address space

This indicates a network conflict. Change the SUBNET_PREFIX in the installation directory /data/safeline/.env to a different subnet.

Other errors such as "It does not belong to any of this network's subnets..."

For various other errors, consider uninstalling and then reinstalling SafeLine following the provided uninstallation instructions.

How to Customize the SafeLine Installation Path?

Based on the latest compose.yaml, you can manually modify the SAFELINE_DIR variable in the .env file.

Can SafeLine and Business Services Be Deployed on the Same Machine?

Yes, they can be deployed on the same machine, but it is not recommended as the machine load will be higher compared to separate deployments.

Is SafeLine Supported on macOS/Windows?

The community edition does not support macOS/Windows. For such requirements, please inquire about the enterprise edition.

How to Change the Default Port for SafeLine Management?

For example, if port 9443 is already occupied.

Use ss -antp | grep LISTEN to check port usage and find an available port.
Modify the hidden .env file in the installation directory (default is safeline) and manually add the MGT_PORT variable.
After modifying the file, a restart is required to take effect.
In the installation directory (default safeline), run:

docker compose down && docker compose up -d

Recommended Configuration

Choose based on your business needs, and it is recommended to match the bandwidth with the origin server.

For standalone SafeLine deployment:

• If the business QPS (queries per second) is below 100, a configuration of at least 2 CPU cores and 4 GB of RAM is recommended.
• If the business QPS is between 100 and 1000, a configuration of at least 4 CPU cores and 8 GB of RAM is recommended.
• If the business QPS is above 1000, a configuration of at least 8 CPU cores and 16 GB of RAM is recommended.

Note: These recommendations are for reference only. It is advised to test according to your business needs before finalizing the server configuration.

Upgrade Issues

Compatibility Issues After Upgrade

When upgrading across multiple major versions, data incompatibility might occur, causing the server to fail to start.

To avoid this, back up your data before upgrading across multiple versions (more than one major version). If the upgrade fails, you can try reinstalling to resolve the issue.

Upgrade Path Error

Executing in the wrong directory (e.g., a subdirectory of SafeLine) can prevent a successful upgrade.

Switch to the installation directory before performing the upgrade. The default directory is /data/safeline.

Configuration Backup and Restore

Concerned about configuration changes during the upgrade process?

Backup: Back up all files in the installation directory. The default directory is /data/safeline.

Restore: Place the backup contents back into the installation directory and run:docker compose down && docker compose up -d.Then restart SafeLine.

API Error or Docker Status Abnormal After Upgrade

Restart Docker.

Original Configuration Not Working After Upgrade

In rare cases, the original configuration might not take effect. Deleting and reconfiguring should resolve the issue.