update README
This commit is contained in:
154
README.md
154
README.md
@@ -1,78 +1,112 @@
|
||||
SafelineAPI
|
||||
=================
|
||||
# SafelineAPI
|
||||
|
||||
Small CLI to request and upsert TLS certificates (DNS-01) with multiple DNS provider backends. This repo now includes Cloudflare DNS provider support via the lego provider.
|
||||
A lightweight CLI tool that automatically manages TLS/SSL certificates for SafeLine instances using DNS-01 validation. It supports multiple DNS providers, making it easy to automate certificate renewal and updates across your infrastructure.
|
||||
|
||||
## Prerequisites
|
||||
- Go toolchain (only required to build from source)
|
||||
- A SafeLine API token (set in `config.json`)
|
||||
- Cloudflare API token (scoped) or Global API key + account email
|
||||
## What It Does
|
||||
|
||||
## Quick start
|
||||
SafelineAPI simplifies TLS certificate management by:
|
||||
- **Automatically requesting new certificates** from Let's Encrypt using DNS-01 validation
|
||||
- **Updating existing certificates** in your SafeLine WAF instance
|
||||
- **Supporting multiple DNS providers** (Cloudflare, Tencent Cloud, Aliyun, Huawei Cloud, WestCN)
|
||||
- **Running as a scheduled service** on Linux (systemd) or Windows
|
||||
- **Checking certificate expiration** and renewing before they expire
|
||||
|
||||
1. Copy `config.example.json` to `config.json` and fill in your values.
|
||||
Perfect for users who want hands-off certificate management integrated with SafeLine!
|
||||
|
||||
2. Build (optional):
|
||||
```powershell
|
||||
cd C:\Users\samge\coding\SafelineAPI-1
|
||||
go build -o safelineApi.exe ./cmd/safelineApi
|
||||
```
|
||||
## Quick Start
|
||||
|
||||
3. Run:
|
||||
```powershell
|
||||
# using built binary
|
||||
.\safelineApi.exe
|
||||
### Download & Run (Easiest)
|
||||
|
||||
# or directly with go
|
||||
go run ./cmd/safelineApi -- -t "<SafeLineApiToken>" -D "Cloudflare" -e "you@example.com"
|
||||
```
|
||||
1. **Download a pre-built binary** from [Releases](../../releases)
|
||||
2. **Follow the setup guide** → see [INSTALL.md](INSTALL.md)
|
||||
|
||||
Configuration notes
|
||||
- The main configuration file is `config.json` in the project root.
|
||||
- To use Cloudflare for DNS-01, set `ApplyCert.DNSProviderConfig.DNSProvider` to `Cloudflare` and set `ApplyCert.DNSProviderConfig.Cloudflare.APIToken` to a scoped API token with `Zone:DNS:Edit` permission.
|
||||
- If you must use the global API key, set `Cloudflare.APIKey` and `Cloudflare.Email` instead (less secure).
|
||||
### Or Build from Source
|
||||
|
||||
Docs
|
||||
- See `docs/CONFIGURATION.md` for detailed configuration and troubleshooting steps.
|
||||
- See `docs/cloudflare.md` for a short Cloudflare-specific guide.
|
||||
|
||||
Security
|
||||
- Prefer scoped API tokens over global keys.
|
||||
- Keep `config.json` out of source control; use environment variables or secret management in production.
|
||||
|
||||
Need anything else?
|
||||
- I can add a small PowerShell script to run the app with environment variable support or create a release artifact (Windows exe) if you'd like.
|
||||
|
||||
Linux usage (systemd)
|
||||
|
||||
Most users run this on a Linux host. Below are recommended steps to install and run SafelineAPI as a service.
|
||||
|
||||
1. Build on the target machine (or cross-compile):
|
||||
```bash
|
||||
cd /opt
|
||||
git clone <your-repo-url> safelineapi
|
||||
cd safelineapi
|
||||
git clone <your-repo-url>
|
||||
cd SafelineAPI
|
||||
go build -o safelineApi ./cmd/safelineApi
|
||||
```
|
||||
|
||||
2. Place your `config.json` in `/opt/safelineapi/config.json` (or edit accordingly). You can use `config.example.json` as a starting point.
|
||||
## Installation & Setup
|
||||
|
||||
For detailed setup instructions, see **[INSTALL.md](INSTALL.md)** which covers:
|
||||
- ✅ Using pre-built release binaries
|
||||
- ✅ Building from source (Linux, Windows, macOS)
|
||||
- ✅ Configuring the application
|
||||
- ✅ Running as a service on Linux (systemd)
|
||||
- ✅ Running as a service on Windows (NSSM, Task Scheduler)
|
||||
- ✅ Troubleshooting
|
||||
|
||||
## Configuration
|
||||
|
||||
1. Copy `config.example.json` to `config.json`
|
||||
2. Fill in your SafeLine API token and DNS provider credentials
|
||||
3. Run with: `./safelineApi config.json`
|
||||
|
||||
For detailed configuration options, see [docs/CONFIGURATION.md](docs/CONFIGURATION.md)
|
||||
|
||||
## DNS Providers
|
||||
|
||||
Currently supported:
|
||||
- **Cloudflare** - Recommended for most users
|
||||
- **Tencent Cloud** - For Chinese users
|
||||
- **Aliyun (Alibaba Cloud)** - For Chinese users
|
||||
- **Huawei Cloud** - For Chinese users
|
||||
- **WestCN** - For Chinese users
|
||||
|
||||
See [docs/cloudflare.md](docs/cloudflare.md) for Cloudflare-specific setup.
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
- ✅ Use **scoped API tokens** instead of global keys (especially for Cloudflare)
|
||||
- ✅ Keep `config.json` **out of source control**
|
||||
- ✅ Restrict file permissions on `config.json` (600 on Linux)
|
||||
- ✅ Run the service as an **unprivileged user**
|
||||
- ✅ Use environment variables or secret management in production
|
||||
|
||||
## Documentation
|
||||
|
||||
- [INSTALL.md](INSTALL.md) - Complete installation and setup guide
|
||||
- [CONFIGURATION.md](docs/CONFIGURATION.md) - Detailed configuration reference
|
||||
- [cloudflare.md](docs/cloudflare.md) - Cloudflare-specific setup guide
|
||||
|
||||
## Development
|
||||
|
||||
### Prerequisites (for building from source)
|
||||
- Go 1.23 or later
|
||||
- Git
|
||||
|
||||
### Build Commands
|
||||
|
||||
3. Install systemd unit (example unit available at `contrib/safelineapi.service`):
|
||||
```bash
|
||||
sudo cp contrib/safelineapi.service /etc/systemd/system/
|
||||
sudo useradd --system --no-create-home safeline || true
|
||||
sudo chown -R safeline:safeline /opt/safelineapi
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable --now safelineapi.service
|
||||
sudo journalctl -u safelineapi.service -f
|
||||
# Build for current platform
|
||||
make build
|
||||
|
||||
# Build for all platforms (Linux & Windows)
|
||||
make build-all
|
||||
|
||||
# Run tests
|
||||
make test
|
||||
|
||||
# Format code
|
||||
make fmt
|
||||
```
|
||||
|
||||
4. Alternatively run with the provided helper script (uses environment variables or builds if missing):
|
||||
```bash
|
||||
chmod +x scripts/run.sh
|
||||
SAFELINE_API_TOKEN="..." DNS_PROVIDER=Cloudflare CONTACT_EMAIL="you@example.com" ./scripts/run.sh
|
||||
```
|
||||
## Automated Releases
|
||||
|
||||
Notes
|
||||
- The `contrib/safelineapi.service` unit assumes files live in `/opt/safelineapi` and the binary is `/opt/safelineapi/safelineApi`. Adjust paths to fit your setup.
|
||||
- For production, run the service as a dedicated unprivileged user and keep `config.json` permissions restricted.
|
||||
This project uses **Gitea Actions** to automatically build and release binaries for:
|
||||
- Linux: amd64, ARM64, ARMv7, 386, PowerPC 64LE
|
||||
- Windows: amd64, 386
|
||||
|
||||
Releases are triggered by git tags (e.g., `v1.0.0`, `v1.0.1`)
|
||||
|
||||
## License
|
||||
|
||||
See LICENSE file for details.
|
||||
|
||||
## Support
|
||||
|
||||
- Found a bug? Create an issue
|
||||
- Have a question? Check the docs first, then create a discussion
|
||||
- Want to contribute? Pull requests welcome!
|
||||
|
||||
Reference in New Issue
Block a user