SafelineAPI/INSTALL.md

# SafelineAPI - Installation & Setup Guide

## Table of Contents
1. [Requirements](#requirements)
2. [Option 1: Using Pre-Built Releases](#option-1-using-pre-built-releases)
3. [Option 2: Building from Source](#option-2-building-from-source)
4. [Configuration](#configuration)
5. [Running on Linux](#running-on-linux)
6. [Running on Windows](#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](https://go.dev/dl/))
- **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](../../releases) 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)
```bash
chmod +x safelineApi-linux-amd64
```

### Step 3: Prepare Configuration
See [Configuration](#configuration) section below.

### Step 4: Run or Install as Service
See [Running on Linux](#running-on-linux) or [Running on Windows](#running-on-windows) sections.

---

## Option 2: Building from Source

### Step 1: Clone the Repository
```bash
git clone https://github.com/yourusername/SafelineAPI.git
cd SafelineAPI
```

### Step 2: Install Dependencies
```bash
go mod download
go mod tidy
```

### Step 3: Build the Binary

**For Linux:**
```bash
# Build for your current system
make build

# Build for all platforms
make build-all
```

**For Windows (PowerShell):**
```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:**
```bash
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:
```bash
# 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:

```json
{
  "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](docs/CONFIGURATION.md) for detailed configuration options.

---

## Running on Linux

### Option A: Manual Run

**1. Navigate to the binary location:**
```bash
cd /path/to/safelineapi
```

**2. Run with configuration file:**
```bash
./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):**
```bash
sudo useradd -r -s /bin/false safeline
```

**2. Set up directories:**
```bash
sudo mkdir -p /opt/safelineapi
sudo mkdir -p /opt/safelineapi/certs
sudo mkdir -p /var/log/safelineapi
```

**3. Copy files:**
```bash
# 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`:
```ini
[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:**
```bash
sudo systemctl daemon-reload
sudo systemctl enable safelineapi
sudo systemctl start safelineapi
```

**6. Check status:**
```bash
sudo systemctl status safelineapi
sudo journalctl -u safelineapi -f  # Follow logs
```

### Option C: Run with Cron (for periodic updates)

Add to crontab:
```bash
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:**
```powershell
cd "C:\Program Files\SafelineAPI"
```

**3. Run the application:**
```powershell
# 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:**
```powershell
# 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:**
```powershell
nssm start SafelineAPI
```

**5. Check status:**
```powershell
nssm status SafelineAPI
```

**6. View logs:**
```powershell
# NSSM logs to Event Viewer by default
# Or check the log file NSSM creates (path shown in service properties)
```

**7. Stop the service:**
```powershell
nssm stop SafelineAPI
```

**8. Uninstall the service:**
```powershell
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)
```bash
# 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)
```powershell
# Check NSSM status
nssm status SafelineAPI

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

### DNS Provider Issues
See [CONFIGURATION.md](docs/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):**
   ```bash
   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](docs/CONFIGURATION.md) for configuration details
- Check [cloudflare.md](docs/cloudflare.md) for Cloudflare-specific setup
- Create an issue on GitHub/Gitea for bugs