diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..363f9b3 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,411 @@ +# 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`: Your DNS provider (Cloudflare, TencentCloud, AliCloud, HuaweiCloud, WestCN) + +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 diff --git a/config.json b/config.json index 9723e78..f0c12c7 100644 --- a/config.json +++ b/config.json @@ -12,36 +12,10 @@ "SavePath": "/tmp/ssl", "DNSProviderConfig": { "DNSProvider": "xxx", - "TencentCloud": { - "SecretId": "xxx", - "SecretKey": "xxx" - }, - "AliCloud": { - "AccessKeyId": "xxx", - "AccessKeySecret": "xxx", - "RAMRole": "xxx (optional)", - "STSToken": "xxx (optional)" - }, - "HuaweiCloud": { - "AccessKeyId": "xxx", - "Region": "xxx", - "SecretAccessKey": "xxx" - }, - "WestCN": { - "Username": "xxx", - "Password": "xxx" - }, - "RainYun": { - "ApiKey": "xxx" - }, "Cloudflare": { "APIToken": "xxx", "APIKey": "xxx (optional)", "Email": "your-email@example.com (optional)" - }, - "Dode": { - "Token": "xxx" } - } } } \ No newline at end of file