mirror of
https://github.com/tiennm99/keepalive.git
synced 2026-10-11 12:19:02 +00:00
tiennm99
e445b5cbc5
The README now covers what keepalive is, a quick start, the adapter table, and links. Reference material moves to docs/: configuration (every option, per-adapter keys, validation), deployment (Compose, Coolify, Docker, source), how it works (writes, retries, timeouts, logging), known issues (PostgreSQL public-schema permissions and Aiven's ACL key-pattern tilde, by log line), and adding an adapter (now including ConfigKeys registration). .gitignore also excludes config.yaml, matching .dockerignore.
70 lines
2.9 KiB
Markdown
70 lines
2.9 KiB
Markdown
# keepalive
|
|
|
|
**Stop free-tier databases from pausing.** keepalive is a tiny Go daemon that writes to each of your hosted datastores on a schedule, so idle-shutdown policies never trigger.
|
|
|
|
- **One config, many services.** Keep Redis, PostgreSQL, MySQL, MongoDB, and Couchbase instances alive from a single process.
|
|
- **Cheapest possible write.** Each tick increments one counter; nothing else in your database is touched.
|
|
- **Self-healing.** Failed services retry every minute and recreate their counter if it disappears, without affecting the others.
|
|
- **Small and safe.** A static, distroless, non-root image with no ports, and connection strings are kept out of logs.
|
|
|
|
Works with Redis Cloud, Upstash, Aiven (PostgreSQL, MySQL, Valkey), Supabase, YugabyteDB, CockroachDB, MongoDB Atlas, Couchbase Capella, and any self-hosted Redis-, Valkey-, PostgreSQL-, MySQL-, MongoDB-, or Couchbase-compatible server.
|
|
|
|
## Quick start
|
|
|
|
Write a `config.yml`:
|
|
|
|
```yaml
|
|
interval: 1h
|
|
|
|
services:
|
|
- name: upstash
|
|
adapter: redis
|
|
config:
|
|
url: rediss://default:PASSWORD@example.upstash.io:6379
|
|
|
|
- name: supabase
|
|
adapter: postgresql
|
|
config:
|
|
url: postgresql://USER:PASSWORD@aws-0-region.pooler.supabase.com:5432/postgres?sslmode=require
|
|
|
|
- name: atlas
|
|
adapter: mongodb
|
|
config:
|
|
uri: mongodb+srv://USER:PASSWORD@cluster0.example.mongodb.net
|
|
database: keepalive
|
|
collection: counter
|
|
```
|
|
|
|
Run it:
|
|
|
|
```bash
|
|
git clone https://github.com/tiennm99/keepalive && cd keepalive
|
|
# put your config.yml here (see config.example.yml for every adapter)
|
|
docker compose up -d --build
|
|
docker compose logs -f
|
|
```
|
|
|
|
Each service logs a line like `[upstash] counter: 42` on every tick.
|
|
|
|
## Adapters
|
|
|
|
| `adapter` | Use it for |
|
|
| ------------------------- | ----------------------------------------------------------------- |
|
|
| `redis` | Redis, Valkey, Dragonfly, KeyDB, Garnet, Upstash, Redis Cloud |
|
|
| `postgresql` / `postgres` | PostgreSQL, Supabase, Aiven, YugabyteDB, CockroachDB |
|
|
| `mysql` | MySQL, MariaDB, Aiven for MySQL, TiDB |
|
|
| `mongodb` / `mongo` | MongoDB Atlas, Azure DocumentDB, FerretDB, Cosmos DB for MongoDB |
|
|
| `couchbase` | Couchbase Capella and self-hosted Couchbase |
|
|
|
|
## Documentation
|
|
|
|
- [Configuration](docs/configuration.md): every option, per-adapter keys, and validation rules.
|
|
- [Deployment](docs/deployment.md): Docker Compose, Coolify, plain Docker, and running from source.
|
|
- [How it works](docs/how-it-works.md): what each adapter writes, retries, timeouts, and shutdown.
|
|
- [Known issues](docs/known-issues.md): permission errors and other setup problems, by log line.
|
|
- [Adding an adapter](docs/adding-an-adapter.md): plug in a new datastore.
|
|
|
|
## License
|
|
|
|
Apache-2.0. See [LICENSE](LICENSE).
|