add cloudflare docs

README.md

@@ -6,7 +6,7 @@
 
 [![Community](https://img.shields.io/badge/chv.to-community-blue?style=flat-square)](https://chv.to/community)
 
-Dockerfile driven template project for building and running container images for Chevereto V4 projects.
+Dockerfile driven template project for building images and manage containers for Chevereto V4 projects.
 
 > **Warning**: Do not publish Docker images to a public registry when using a paid Chevereto edition as its [commercial license](https://chevereto.com/license) restricts re-distribution rights.
 
@@ -15,6 +15,7 @@ Dockerfile driven template project for building and running container images for
 * One-click commands using `make`
 * Built-in nginx-proxy for multiple instances
 * Pure Docker instructions
+* Integrated with CloudFlare API
 
 ## Requirements
 
@@ -27,10 +28,11 @@ Dockerfile driven template project for building and running container images for
   * [Docker](https://docs.docker.com/)
   * [Compose V2](https://docs.docker.com/compose/cli-command/) `docker compose`
 * Hostname pointing to server
+* See [CLOUDFLARE](./docs/CLOUDFLARE.md) when using CloudFlare
 
 ## Pure Docker
 
-Refer to [PURE-DOCKER](docs/PURE-DOCKER.md) for all pure docker commands.
+Refer to [PURE-DOCKER](docs/PURE-DOCKER.md) for a complete pure Docker command reference.
 
 ```sh
 docker run -d \
@@ -86,23 +88,27 @@ make proxy EMAIL_HTTPS=mail@yourdomain.tld
 make image
 ```
 
-## Spawn Chevereto instance
+## Create a NAMESPACE
 
-* Setup a [NAMESPACE](docs/NAMESPACE.md)
+* Setup a [NAMESPACE](docs/NAMESPACE.md) for your website project
 
 ```sh
 make namespace NAMESPACE=yourproject HOSTNAME=yourdomain.tld
 ```
 
-* Run the container
+## Spawn Chevereto instance
 
-💡 When using free edition pass `EDITION=free`.
+* Run the Chevereto container using [spawn](docs/DOCKER-COMPOSE.md#spawn):
 
 ```sh
-make up-d NAMESPACE=yourproject
+make spawn NAMESPACE=yourproject
 ```
 
-To create more instances repeat the steps (setup namespace, run container).
+* 💡 When using free edition pass `EDITION=free`:
+
+```sh
+make spawn NAMESPACE=yourproject EDITION=free
+```
 
 ## Documentation
 
@@ -112,6 +118,7 @@ To create more instances repeat the steps (setup namespace, run container).
 * [DOCKER-COMPOSE](./docs/DOCKER-COMPOSE.md)
 * [VOLUMES](./docs/VOLUMES.md)
 * [HTTPS](./docs/HTTPS.md)
+* [CLOUDFLARE](./docs/CLOUDFLARE.md)
 * [UPDATING](./docs/UPDATING.md)
 * [PERSISTENT](./docs/PERSISTENT.md)
 * [FEEDBACK](./docs/FEEDBACK.md)

docs/CLOUDFLARE.md

@@ -0,0 +1,74 @@
+# CloudFlare
+
+CloudFlare integration enables to automatically create hostnames (sub-domains) for a given DNS zone. It allows to create/destroy multiple hostnames associated with a Chevereto container running in the same server.
+
+## How it works?
+
+It creates CNAMEs pointing to an **A record** which points to the server. This enables CNAMEs to point to the same server IP by controlling just one record.
+
+```plain
+A     demo.chevereto.cloud -> <SERVER IP>
+CNAME user1.chevereto.cloud -> demo.chevereto.cloud
+CNAME user2.chevereto.cloud -> demo.chevereto.cloud
+...etc
+```
+
+## Setup
+
+* Go to your CloudFlare domain DNS
+* Create an **A record** pointing to server IP (DNS only, do not cache)
+* Get an [API token](#cloudflare-token) for the DNS zone
+* Copy [.env-stock](.env-stock) to `.env` and fill in the values
+
+### .env file
+
+```env
+CLOUDFLARE_TOKEN=
+CLOUDFLARE_ZONE_ID=
+CLOUDFLARE_ACCOUNT_ID=
+CLOUDFLARE_A_NAME=
+```
+
+### CloudFlare Token
+
+`CLOUDFLARE_TOKEN`
+
+* Go to [api-tokens](https://dash.cloudflare.com/profile/api-tokens) and go to **Create Token**
+* Use template **Edit zone DNS**
+* Permissions: **Zone DNS Edit**
+* Resources: **Include Specific zone DOMAIN**
+* Continue to summary and **Create Token**
+
+### CloudFlare Zone/Account ID
+
+You get these values from **domain overview**.
+
+### CloudFlare A Name
+
+`CLOUDFLARE_A_NAME`
+
+The A record used to point CNAMEs generated by this project.
+
+## Commands
+
+**Note:** Following commands must run only after creating the [NAMESPACE](NAMESPACE.md).
+
+### Spawn instance
+
+Refer to [make spawn](DOCKER-COMPOSE.md#spawn).
+
+### Destroy instance
+
+Refer to [make destroy](DOCKER-COMPOSE.md#destroy).
+
+### Create CNAME record
+
+```sh
+make cloudflare--create NAMESPACE=yourproject
+```
+
+### Delete CNAME record
+
+```sh
+make cloudflare--delete NAMESPACE=yourproject
+```

docs/DOCKER-COMPOSE.md

@@ -32,7 +32,7 @@ make up HOSTNAME=que.chevere.org PORT=80
 Example:
 
 ```sh
-make up NAMESPACE=quechevere
+make up NAMESPACE=yourproject
 ```
 
 ### Notes on TARGET
@@ -89,6 +89,28 @@ make down
 make down--volumes
 ```
 
+## Combined commands
+
+### Spawn
+
+💡 Use it right after creating the NAMESPACE.
+
+This will run [cloudflare--create](CLOUDFLARE.md#create-cname-record) and [up-d](DOCKER-COMPOSE.md#up-daemon).
+
+```sh
+make spawn NAMESPACE=yourproject
+```
+
+### Destroy
+
+💡 Use it when needing to complety destroy an instance.
+
+This will run [cloudflare--delete](CLOUDFLARE.md#delete-cname-record), [down--volumes](DOCKER-COMPOSE.md#down-volumes) and remove the [NAMESPACE](NAMESPACE.md).
+
+```sh
+make destroy NAMESPACE=yourproject
+```
+
 ## Troubleshoot
 
 Check if you are running latest Docker version with [Compose V2](https://docs.docker.com/compose/cli-command/) `docker compose` (not `docker-compose`).

docs/NAMESPACE.md

@@ -1,8 +1,8 @@
 # Namespace
 
-💡 To use namespace pass the `NAMESPACE=<namespace>` option on `make` commands.
+Using namespaces is recommended for multi-host setup as rather than passing all the command options you define a file which will load all these variables for each website.
 
-Using namespaces is recommended for multi-host setup as rather than passing all the command options, you define a file which will load all these variables.
+💡 To use namespace pass the `NAMESPACE=<namespace>` option on `make` commands.
 
 ## Creating a namespace