Systemd Service Setup¶

This guide explains how to set up CCProxy API as a systemd user service that starts automatically on user login.

Quick Setup¶

Run the interactive setup script:

./scripts/setup-systemd.sh

The script will: - Detect your uv installation - Ask for your working directory (defaults to a temp folder) - Automatically configure the service with UV_PROJECT pointing to the code - Include ~/.local/bin in PATH if it exists - Enable auto-start on login (optional) - Start the service immediately (optional)

Note: The setup is now simplified - you only need to specify the working directory where the service will run. Everything else is configured automatically.

Manual Setup¶

1. Create Service File¶

Copy the template and customize it:

cp systemd/ccproxy.service.template ~/.config/systemd/user/ccproxy.service

Edit ~/.config/systemd/user/ccproxy.service and replace the placeholders: - {{WORKING_DIR}} - Working directory where the service runs (can be any directory) - {{UV_PATH}} - Path to uv executable - {{UV_PROJECT}} - Path to the CCProxy API project directory - {{USER_PATH}} - Your PATH environment variable (should include ~/.local/bin if it exists) - {{USER_HOME}} - Your home directory - {{EXTRA_ENV}} - Additional environment variables (optional)

2. Enable and Start Service¶

# Reload systemd daemon
systemctl --user daemon-reload

# Enable service to start on login
systemctl --user enable ccproxy.service

# Start service now
systemctl --user start ccproxy.service

# Check status
systemctl --user status ccproxy.service

Service Management¶

Common Commands¶

# Start service
systemctl --user start ccproxy

# Stop service
systemctl --user stop ccproxy

# Restart service
systemctl --user restart ccproxy

# Check status
systemctl --user status ccproxy

# View logs
journalctl --user -u ccproxy -f

# Enable auto-start
systemctl --user enable ccproxy

# Disable auto-start
systemctl --user disable ccproxy

Configuration¶

The service can be configured using: 1. Environment variables in the service file 2. .ccproxy.toml configuration file 3. Command-line arguments in ExecStart

Environment Variable Configuration¶

You can set environment variables directly in the service file using the Environment= directive:

[Service]
# Basic configuration
Environment="PORT=8080"
Environment="HOST=0.0.0.0"
Environment="LOG_LEVEL=DEBUG"
Environment="SECURITY__AUTH_TOKEN=your-secure-token"

# Using nested syntax
Environment="SERVER__PORT=8080"
Environment="LOGGING__LEVEL=INFO"
Environment="LOGGING__FORMAT=json"
Environment="SECURITY__AUTH_TOKEN=your-secure-token"

# Special environment variables
Environment="CONFIG_FILE=/etc/ccproxy/config.toml"
Environment="LOGGING__VERBOSE_API=true"
Environment="CCPROXY_JSON_LOGS=true"

# Scheduler and pricing
Environment="SCHEDULER__ENABLED=true"
Environment="SCHEDULER__PRICING_UPDATE_INTERVAL_HOURS=24"
Environment="PRICING__UPDATE_ON_STARTUP=true"

# Network features (disabled by default for privacy)
# Uncomment to enable specific features
# Environment="SCHEDULER__VERSION_CHECK_ENABLED=true"
# Environment="SCHEDULER__PRICING_UPDATE_ENABLED=true"

Using an Environment File¶

For many environment variables, use an EnvironmentFile:

[Service]
EnvironmentFile=/etc/ccproxy/environment

Create /etc/ccproxy/environment:

# Server configuration
SERVER__HOST=0.0.0.0
SERVER__PORT=8000

# Logging configuration (centralized)
LOGGING__LEVEL=INFO
LOGGING__FORMAT=json
LOGGING__FILE=/var/log/ccproxy/app.log

# Security
SECURITY__AUTH_TOKEN=your-secure-token

# Claude configuration
CLAUDE__CLI_PATH=/usr/local/bin/claude

# Scheduler settings
SCHEDULER__ENABLED=true
SCHEDULER__MAX_CONCURRENT_TASKS=10
SCHEDULER__PRICING_UPDATE_INTERVAL_HOURS=24

# Network features (disabled by default for privacy)
SCHEDULER__VERSION_CHECK_ENABLED=false
SCHEDULER__PRICING_UPDATE_ENABLED=false

# Pricing settings
PRICING__UPDATE_ON_STARTUP=true
PRICING__ENABLE_COST_TRACKING=true

# CORS settings
CORS__ALLOW_ORIGINS=["https://yourdomain.com"]

Complete Service File Example¶

[Unit]
Description=CCProxy API Server
After=network.target

[Service]
Type=exec
WorkingDirectory=/tmp/ccproxy-workdir
ExecStart=/home/user/.local/bin/uv run ccproxy serve

# Environment configuration
Environment="PATH=/home/user/.local/bin:/usr/local/bin:/usr/bin:/bin"
Environment="HOME=/home/user"
Environment="UV_PROJECT=/home/user/ccproxy-api"

# Load additional environment from file
EnvironmentFile=-/etc/ccproxy/environment

# Optional: Override specific settings
Environment="SERVER__PORT=8080"
Environment="LOGGING__LEVEL=INFO"

# Restart configuration
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

For a complete list of environment variables, see CLAUDE.md.

Troubleshooting¶

Service Won't Start¶

Check logs for errors:
```
journalctl --user -u ccproxy -e
```
Verify uv is accessible:
```
which uv
```

Test manual startup:

cd /path/to/ccproxy
uv run ccproxy serve

Permission Issues¶

Ensure the working directory and files are readable by your user:

ls -la /path/to/ccproxy

Check if user lingering is enabled:
```
loginctl show-user $USER | grep Linger
```
Enable lingering if needed:
```
sudo loginctl enable-linger $USER
```

Security Considerations¶

The service runs with your user privileges
Store sensitive configuration in secure files with restricted permissions
Consider using systemd's credential storage for API keys
Review logs regularly for unauthorized access attempts

Multiple Instances¶

To run multiple instances with different configurations:

Create separate service files with unique names
Use different ports for each instance
Configure each with its own config file

Example:

# Development instance
systemctl --user start ccproxy-dev

# Production instance
systemctl --user start ccproxy-prod