sam/SafelineAPI
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

update INSTALL.MD and config example

Browse Source
This commit is contained in:
Sam Geyskens
2025-12-23 16:53:09 +01:00
parent 3ec52f2aea
commit 29e169cbd5
2 changed files with 411 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

411
INSTALL.md Normal file
View File

@@ -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

26
config.json
View File

@@ -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"
}
}
}
}