Best Practices for Deploying S-UI in Production

Deploy S-UI in production by using the idempotent install.sh script, enabling the systemd service with auto-restart, mounting persistent volumes for SQLite and certificates, securing the admin credentials, and terminating TLS via Let's Encrypt or custom certificates.

S-UI is a Go-based web panel for the sing-box proxy engine, maintained in the alireza0/s-ui repository. A production-ready deployment requires idempotent installation, persistent data storage, and secure networking configurations. This guide covers concrete implementations based on the official source code, including specific file paths and automation scripts.

Production Deployment Checklist

Before deploying to production, verify these critical components:

• Run the idempotent installer – The install.sh script automatically downloads the latest binary to /usr/local/s-ui/, creates required folders, and registers a systemd service.
• Enable service supervision – The bundled s-ui.service unit file configures Restart=on-failure for automatic recovery.
• Mount persistent volumes – The docker-compose.yml specifies ./db and ./cert mounts to survive container restarts.
• Provision TLS certificates – Use the built-in ssl_cert_issue_main function in s-ui.sh (lines 82-89) or provide PEM files in the ./cert directory.
• Secure default credentials – Change the default admin/admin pair immediately via the s-ui set_admin command.
• Configure kernel optimization – Enable BBR congestion control via the enable_bbr helper in s-ui.sh (lines 36-44).
• Set resource limits – Define SUI_LOG_LEVEL, SUI_DB_FOLDER, and SUI_BIN_FOLDER environment variables as documented in README.md (lines 31-38).

Systemd Deployment Method

For bare-metal or virtual machine deployments, use the systemd service definition provided in the repository at s-ui.service. This configuration ensures the binary runs with proper working directories and automatic restart behavior.

# /etc/systemd/system/s-ui.service

[Unit]
Description=s-ui Service
After=network.target
Wants=network.target

[Service]
Type=simple
WorkingDirectory=/usr/local/s-ui/
ExecStart=/usr/local/s-ui/sui
Restart=on-failure
RestartSec=10s
Environment=SUI_LOG_LEVEL=info
Environment=SUI_DB_FOLDER=db
Environment=SUI_BIN_FOLDER=bin

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable s-ui
sudo systemctl start s-ui

The main.go file handles graceful shutdown internally, ensuring active connections close properly when the service stops.

Docker Compose Deployment Method

For cloud environments or containerized orchestration, use the official docker-compose.yml configuration. This approach isolates dependencies and simplifies backup operations.

services:
  s-ui:
    image: alireza7/s-ui:latest
    container_name: s-ui
    restart: unless-stopped
    ports:
      - "2095:2095"   # Admin panel

      - "2096:2096"   # Subscription service

    volumes:
      - "./db:/app/db"
      - "./cert:/app/cert"
    environment:
      - SUI_LOG_LEVEL=info
      - SUI_DB_FOLDER=db
      - SUI_BIN_FOLDER=bin

Deploy with:

docker compose up -d

The volume mounts ensure that SQLite databases in database/model/ and TLS certificates persist across image updates.

Security Hardening Practices

Change Default Admin Credentials

The default installation creates an admin/admin account. Change this immediately using the management script:

s-ui set_admin

This command invokes the binary's admin handler implemented in service/user.go, updating the credentials stored in the SQLite database.

Modify Default Ports and Paths

Change the default panel port (2095) and URL path (/app/) to obscure the administration interface:

s-ui set_setting -port <new_port>

Restrict firewall rules to allow inbound traffic on ports 2095 and 2096 only from trusted administrative networks.

TLS Certificate Management

For automatic Let's Encrypt provisioning, use the interactive menu:

s-ui

# Select option 19: SSL Certificate Management

# Select 1: Get SSL

The ssl_cert_issue_main function in s-ui.sh orchestrates acme.sh to obtain certificates and install them into the ./cert directory. Alternatively, mount existing PEM files to ./cert before starting the container.

Performance Optimization

Enable BBR Congestion Control

For improved network throughput on Linux hosts, enable BBR via the provided helper:

s-ui

# Select option 18: Enable BBR

The enable_bbr function in s-ui.sh (lines 36-44) modifies /etc/sysctl.conf to set net.core.default_qdisc=fq and net.ipv4.tcp_congestion_control=bbr.

Resource Allocation

The application core in core/*.go manages the sing-box proxy engine. Ensure the host has sufficient file descriptors and memory allocated for high-concurrency scenarios. The api/apiHandler.go exposes a /metrics endpoint for monitoring connection statistics and resource utilization.

Backup and Monitoring

Database Backups

Automate backups using the utilities in database/backup.go. The SQLite database stored in ./db contains user accounts, inbounds/outbounds configurations, and traffic statistics. Schedule regular copies of this directory to external storage.

Health Monitoring

Check service status via systemd:

systemctl status s-ui

For containerized deployments, use:

docker logs s-ui

The statistics collection logic in service/stats.go tracks user traffic and system health, accessible through the API endpoints defined in api/apiService.go.

Summary

• Use install.sh for repeatable, idempotent installations on new hosts.
• Enable the systemd unit with Restart=on-failure for resilience.
• Mount persistent volumes for ./db and ./cert to prevent data loss.
• Secure the installation by changing default credentials, modifying ports, and enabling TLS via s-ui.sh or custom certificates.
• Optimize networking by enabling BBR congestion control on Linux kernels.
• Monitor health through systemd status checks or the /metrics API endpoint.

Frequently Asked Questions

Should I use systemd or Docker for production deployments?

Use systemd for dedicated bare-metal or virtual machines where you want direct service management and minimal overhead. Use Docker for cloud environments, automated scaling, or when you need quick rollbacks via image tags. Both methods are officially supported and reference the same s-ui.service and docker-compose.yml configurations in the alireza0/s-ui repository.

How do I configure TLS certificates for the S-UI panel?

Run the s-ui management script and select SSL Certificate Management (option 19), then choose Get SSL (option 1). This executes the ssl_cert_issue_main function in s-ui.sh, which uses acme.sh to provision Let's Encrypt certificates into the ./cert directory. For custom certificates, place your fullchain.pem and privkey.pem files in ./cert before starting the service.

Can I change the default admin panel port from 2095?

Yes. Use the command s-ui set_setting -port <new_port> to reconfigure the listening port. You must also update your firewall rules and Docker port mappings if running in a container. The configuration is stored in the SQLite database and loaded on application startup in main.go.

What is BBR and should I enable it?

BBR (Bottleneck Bandwidth and Round-trip propagation time) is a TCP congestion control algorithm that improves network throughput and reduces latency. Enable it via the s-ui menu (option 18) or the enable_bbr function in s-ui.sh. This is recommended for production proxy servers to maximize sing-box performance, but requires Linux kernel 4.9 or later.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}