angelos

Angelos automates the synchronization of DNS Records between your server and cloudflare. Specially useful if you're using Cloudflare tunnels to expose your services to internet.

Roadmap · Report Bug · Request Feature

About The Project

In Greek mythology, Angelos (Ancient Greek: Ἄγγελος) was the first daughter of Zeus and Hera. Let's say you

(back to top)

Prerequisites

• You must already have a Cloudflare Tunnel running.

Configuration

Angelos supports the following environment variables.

Env Var	Default	Description
CLOUDFLARE_ZONE_ID *	N/A	Zone id where your cf domain is. Usually can be seen under API section after selecting a domain in your dashboard or through their api
CLOUDFLARE_API_TOKEN *	N/A	CF Api Token with edit DNS Record Permission. See here
CLOUDFLARE_TUNNEL_URL *	N/A	Your tunnel url that should follow uuid.cfargotunnel.com
PROVIDER	docker	Supported values: docker, traefik. If provider=docker you must pass a docker sock (see docker example) if provider=traefik you must pass TRAEFIK_API_URL
DOCKER_LABEL_HOSTNAME	angelos.hostname	Which docker label will angelos use as a hostname
DOCKER_LABEL_ENABLE	angelos.enabled	If set to false, the service will be ignored
LOG_LEVEL	info	Possible values: silly, trace, debug, info, warn, error, fatal
DRY_RUN	false	If set to true, Angelos will not create or delete DNS records
DELETE_DNS_RECORD_DELAY	300	How many seconds it'll wait to delete a dns record in cf (in case you removed a service by mistake)
ADD_DNS_RECORD_DELAY	60	How many seconds it'll wait to create a dns record in cf (in case you removed a service by mistake)
TRAEFIK_API_URL	N/A	If provider=traefik this must point to Traefik's api url
TRAEFIK_POLL_INTERVAL	600	Indicates how often (in seconds) angelos will check traefik routers

* Required

Running with Docker

docker run \
-e CLOUDFLARE_ZONE_ID=<cloudflare zone> \ # Required
-e CLOUDFLARE_API_TOKEN=<token with edit dns record permission> \ # Required
-e CLOUDFLARE_TUNNEL_URL=<tunnel-uuid.cfargotunnel.com> \ # Required
-e PROVIDER=docker \ # for more options, see Configuration
-v /var/run/docker.sock:/var/run/docker.sock \ # if provider=docker
ghcr.io/wovalle/angelos

Running with Docker-Compose

angelos:
  image: ghcr.io/wovalle/angelos
  container_name: angelos
  environment:
    - CLOUDFLARE_ZONE_ID=<cloudflare zone> # Required
    - CLOUDFLARE_API_TOKEN=<token with edit dns record permission> # Required
    - CLOUDFLARE_TUNNEL_URL=<tunnel-uuid.cfargotunnel.com> # Required
    - PROVIDER=docker
    # for more options, see Configuration
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock # if provider=docker

Running manually

Angelos is a typescript project. You'll need node 14 or later.

• Clone the project from github:

git clone git@github.com:wovalle/angelos.git

• Install the dependencies:

yarn # or npm install

• Create a credentials file

Copy the existing .env.example and name it .env

• Run the project

yarn start # or npm start

• Have fun!

(back to top)

Contributing

Have a bug or a feature request? Please search the issues to prevent duplication. If you couldn't find what you were looking for, proceed to open a new one. Pull requests are welcome!

Commiting

This repo uses Conventional Commits as the commit messages convention. Commits must follow Angular's git commit guidelines.

Supported commit types (source):

• feat: A new feature
• fix: A bug fix
• docs: Documentation only changes
• style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
• refactor: A code change that neither fixes a bug nor adds a feature
• perf: A code change that improves performance
• test: Adding missing or correcting existing tests
• chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

Releases

This repo uses Github Actions to automate workflows like run tests and create releases. It uses Sematic Release to bump the versions according to their commit messages.

(back to top)

Contributors

This project follows the all-contributors specification. Contributions of any kind welcome!

Thanks goes to these wonderful people (emoji key):

Willy Ovalle 💻 📖 💡 🤔 ⚠️

License

MIT © Willy Ovalle. See LICENSE for details.

(back to top)