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
|
## What It Does
|
||||||
- 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
|
|
||||||
|
|
||||||
## 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):
|
## Quick Start
|
||||||
```powershell
|
|
||||||
cd C:\Users\samge\coding\SafelineAPI-1
|
|
||||||
go build -o safelineApi.exe ./cmd/safelineApi
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Run:
|
### Download & Run (Easiest)
|
||||||
```powershell
|
|
||||||
# using built binary
|
|
||||||
.\safelineApi.exe
|
|
||||||
|
|
||||||
# or directly with go
|
1. **Download a pre-built binary** from [Releases](../../releases)
|
||||||
go run ./cmd/safelineApi -- -t "<SafeLineApiToken>" -D "Cloudflare" -e "you@example.com"
|
2. **Follow the setup guide** → see [INSTALL.md](INSTALL.md)
|
||||||
```
|
|
||||||
|
|
||||||
Configuration notes
|
### Or Build from Source
|
||||||
- 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).
|
|
||||||
|
|
||||||
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
|
```bash
|
||||||
cd /opt
|
git clone <your-repo-url>
|
||||||
git clone <your-repo-url> safelineapi
|
cd SafelineAPI
|
||||||
cd safelineapi
|
|
||||||
go build -o safelineApi ./cmd/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
|
```bash
|
||||||
sudo cp contrib/safelineapi.service /etc/systemd/system/
|
# Build for current platform
|
||||||
sudo useradd --system --no-create-home safeline || true
|
make build
|
||||||
sudo chown -R safeline:safeline /opt/safelineapi
|
|
||||||
sudo systemctl daemon-reload
|
# Build for all platforms (Linux & Windows)
|
||||||
sudo systemctl enable --now safelineapi.service
|
make build-all
|
||||||
sudo journalctl -u safelineapi.service -f
|
|
||||||
|
# Run tests
|
||||||
|
make test
|
||||||
|
|
||||||
|
# Format code
|
||||||
|
make fmt
|
||||||
```
|
```
|
||||||
|
|
||||||
4. Alternatively run with the provided helper script (uses environment variables or builds if missing):
|
## Automated Releases
|
||||||
```bash
|
|
||||||
chmod +x scripts/run.sh
|
|
||||||
SAFELINE_API_TOKEN="..." DNS_PROVIDER=Cloudflare CONTACT_EMAIL="you@example.com" ./scripts/run.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
Notes
|
This project uses **Gitea Actions** to automatically build and release binaries for:
|
||||||
- The `contrib/safelineapi.service` unit assumes files live in `/opt/safelineapi` and the binary is `/opt/safelineapi/safelineApi`. Adjust paths to fit your setup.
|
- Linux: amd64, ARM64, ARMv7, 386, PowerPC 64LE
|
||||||
- For production, run the service as a dedicated unprivileged user and keep `config.json` permissions restricted.
|
- 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