SafelineAPI/INSTALL.md

SafelineAPI - Installation & Setup Guide

Table of Contents

1. Requirements
2. Option 1: Using Pre-Built Releases
3. Option 2: Building from Source
4. Configuration
5. Running on Linux
6. Running on Windows

---

Requirements

For Using Pre-Built Releases

• Linux: glibc-based distributions (most common Linux distros)
• Windows: Windows 7 or later (64-bit or 32-bit)
• A SafeLine API token
• Credentials for your DNS provider (Cloudflare, Tencent Cloud, Aliyun, Huawei Cloud, or WestCN)

For Building from Source

• Go: Version 1.23 or later (download here)
• Git: For cloning the repository
• A SafeLine API token
• DNS provider credentials

---

Option 1: Using Pre-Built Releases

Step 1: Download the Binary

Go to the Releases page and download the appropriate binary for your system:

Linux:

• safelineApi-linux-amd64 - Most common, Intel/AMD 64-bit
• safelineApi-linux-arm64 - ARM 64-bit (Apple Silicon, newer ARM servers)
• safelineApi-linux-armv7 - ARM 32-bit (Raspberry Pi, older ARM)
• safelineApi-linux-386 - 32-bit Intel/AMD
• safelineApi-linux-ppc64le - PowerPC 64-bit

Windows:

• safelineApi-windows-amd64.exe - 64-bit (most common)
• safelineApi-windows-386.exe - 32-bit

Step 2: Make it Executable (Linux only)

chmod +x safelineApi-linux-amd64

Step 3: Prepare Configuration

See Configuration section below.

Step 4: Run or Install as Service

See Running on Linux or Running on Windows sections.

---

Option 2: Building from Source

Step 1: Clone the Repository

git clone https://github.com/yourusername/SafelineAPI.git
cd SafelineAPI

Step 2: Install Dependencies

go mod download
go mod tidy

Step 3: Build the Binary

For Linux:

# Build for your current system
make build

# Build for all platforms
make build-all

For Windows (PowerShell):

# Build for current system
go build -o safelineApi.exe ./cmd/safelineApi

# Build for all platforms
@"
`$goos = @('linux', 'windows')
`$goarch = @('amd64', '386', 'arm64')
foreach (`$os in `$goos) {
    foreach (`$arch in `$goarch) {
        `$env:GOOS = `$os
        `$env:GOARCH = `$arch
        `$ext = if (`$os -eq 'windows') { '.exe' } else { '' }
        go build -o bin/safelineApi-`${os}-`${arch}`${ext} ./cmd/safelineApi
    }
}
"@ | powershell -NoProfile -

For macOS:

go build -o safelineApi ./cmd/safelineApi

The binary will be created in the bin/ directory or current directory.

---

Configuration

Step 1: Create Configuration File

Copy the example configuration:

# Linux/macOS
cp config.example.json config.json

# Windows (PowerShell)
Copy-Item config.example.json config.json

Step 2: Edit Configuration

Open config.json and fill in your details:

{
  "SafeLine": {
    "Host": {
      "HostName": "your-safeline-host.com",
      "Port": "1443"
    },
    "ApiToken": "your-api-token-here"
  },
  "ApplyCert": {
    "Days": 30,
    "Email": "your-email@example.com",
    "SavePath": "/tmp/ssl",
    "DNSProviderConfig": {
      "DNSProvider": "Cloudflare",
      "Cloudflare": {
        "APIToken": "your-cloudflare-scoped-token"
      }
    }
  }
}

Important:

• SafeLine.Host.HostName: Your SafeLine instance hostname
• SafeLine.ApiToken: Your SafeLine API token
• ApplyCert.Email: Email for Let's Encrypt notifications
• ApplyCert.SavePath: Where to save certificates (Linux: /opt/safelineapi/certs, Windows: C:\SafelineAPI\certs)
• DNSProvider: Set to Cloudflare (additional providers coming in future versions)
• Cloudflare.APIToken: Your scoped Cloudflare API token with Zone:DNS:Edit permissions

See CONFIGURATION.md for detailed configuration options.

---

Running on Linux

Option A: Manual Run

1. Navigate to the binary location:

cd /path/to/safelineapi

2. Run with configuration file:

./safelineApi-linux-amd64 config.json

3. Check the output:

[INFO] Starting SafelineAPI...
[INFO] Loaded configuration from config.json
[INFO] Connecting to SafeLine instance...
[INFO] Found X certificates to update

Option B: Install as Systemd Service (Recommended)

1. Create service user (optional but recommended):

sudo useradd -r -s /bin/false safeline

2. Set up directories:

sudo mkdir -p /opt/safelineapi
sudo mkdir -p /opt/safelineapi/certs
sudo mkdir -p /var/log/safelineapi

3. Copy files:

# Copy binary
sudo cp safelineApi-linux-amd64 /opt/safelineapi/safelineApi
sudo chmod +x /opt/safelineapi/safelineApi

# Copy configuration
sudo cp config.json /opt/safelineapi/config.json
sudo chmod 600 /opt/safelineapi/config.json  # Only readable by owner

# Set ownership
sudo chown -R safeline:safeline /opt/safelineapi
sudo chown -R safeline:safeline /var/log/safelineapi

4. Create systemd service file:

Create /etc/systemd/system/safelineapi.service:

[Unit]
Description=SafelineAPI Service
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/safelineapi
ExecStart=/opt/safelineapi/safelineApi config.json
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
User=safeline
Group=safeline

[Install]
WantedBy=multi-user.target

5. Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable safelineapi
sudo systemctl start safelineapi

6. Check status:

sudo systemctl status safelineapi
sudo journalctl -u safelineapi -f  # Follow logs

Option C: Run with Cron (for periodic updates)

Add to crontab:

crontab -e

# Run every day at 2 AM
0 2 * * * /opt/safelineapi/safelineApi /opt/safelineapi/config.json >> /var/log/safelineapi/cron.log 2>&1

---

Running on Windows

Option A: Manual Run (Command Prompt or PowerShell)

1. Open Command Prompt or PowerShell

2. Navigate to the folder with the binary:

cd "C:\Program Files\SafelineAPI"

3. Run the application:

# With config file
.\safelineApi-windows-amd64.exe config.json

# Or use interactive mode
.\safelineApi-windows-amd64.exe

4. Expected output:

[INFO] Starting SafelineAPI...
[INFO] Loaded configuration from config.json
[INFO] Connecting to SafeLine instance...
[INFO] Found X certificates to update

Option B: Install as Windows Service (Recommended)

Using NSSM (Non-Sucking Service Manager):

1. Download NSSM:

• Download from https://nssm.cc/download
• Extract to a folder in PATH or note the full path

2. Open PowerShell as Administrator

3. Install the service:

# If nssm is in PATH
nssm install SafelineAPI "C:\Program Files\SafelineAPI\safelineApi-windows-amd64.exe" "C:\Program Files\SafelineAPI\config.json"

# Or with full path to nssm
"C:\Path\To\nssm.exe" install SafelineAPI "C:\Program Files\SafelineAPI\safelineApi-windows-amd64.exe" "C:\Program Files\SafelineAPI\config.json"

4. Start the service:

nssm start SafelineAPI

5. Check status:

nssm status SafelineAPI

6. View logs:

# NSSM logs to Event Viewer by default
# Or check the log file NSSM creates (path shown in service properties)

7. Stop the service:

nssm stop SafelineAPI

8. Uninstall the service:

nssm remove SafelineAPI confirm

Option C: Windows Task Scheduler (Alternative)

1. Open Task Scheduler (Win+R → taskschd.msc)

2. Create Basic Task:

• Name: SafelineAPI
• Trigger: Daily at 2 AM
• Action: Start program
  • Program: C:\Program Files\SafelineAPI\safelineApi-windows-amd64.exe
  • Arguments: C:\Program Files\SafelineAPI\config.json

3. Configure permissions:

• General tab → "Run with highest privileges" (optional)
• Run whether user is logged in or not

---

Troubleshooting

Application Won't Start

• Check config.json syntax: Use an online JSON validator
• Check file permissions: Ensure the application can read config.json
• Check SafeLine API token: Verify it's correct and hasn't expired
• Check network: Ensure you can reach your SafeLine instance

Service Won't Start (Linux)

# Check logs
sudo journalctl -u safelineapi -n 50

# Check service status
sudo systemctl status safelineapi

# Manually run to see errors
sudo -u safeline /opt/safelineapi/safelineApi /opt/safelineapi/config.json

Service Won't Start (Windows)

# Check NSSM status
nssm status SafelineAPI

# Check event logs
Get-EventLog -LogName Application -Source SafelineAPI -Newest 10

DNS Provider Issues

See CONFIGURATION.md for DNS provider-specific setup.

---

Security Best Practices

1. Protect config.json:

   • Linux: sudo chmod 600 /opt/safelineapi/config.json
   • Windows: Set ACL to allow only service user

2. Use environment variables (optional):

   export SAFELINE_API_TOKEN="your-token"
   export SAFELINE_HOST="your-host"
   

3. Use scoped API tokens where possible (e.g., Cloudflare scoped tokens)

4. Keep certificates secure:

   • Ensure SavePath directory is not world-readable
   • Regularly back up certificates

---

Getting Help

• Check CONFIGURATION.md for configuration details
• Check cloudflare.md for Cloudflare-specific setup
• Create an issue on GitHub/Gitea for bugs