diff --git a/README.md b/README.md index 96f7b60..92141ac 100644 --- a/README.md +++ b/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 "" -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 safelineapi -cd safelineapi +git clone +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!