update docs

README.md

@@ -23,53 +23,11 @@ A feature-complete fork of [@kallewoof]'s [bitcoin-faucet] built on the PHP+Redi
 
 ## Installation
 
-### Bare Metal (production)
-
 1. Set up a Redis instance
 2. Set up a signet network on a Bitcoin Core or Knots node. This node should have a wallet that receives the mining rewards or otherwise plenty of funds to give out. You can refer to [BcnBitcoinOnly/signet-playground](https://github.com/BcnBitcoinOnly/signet-playground) for more information.
 3. Clone this project, checkout the latest tag and install the PHP dependencies with `composer install --no-dev --classmap-authoritative`
 4. Set up a webserver with FastCGI support and configure it properly, including the faucet's environment variables (see below). Caddy is recommended for its ease of use.
 
-### Docker (development)
-
-For development tasks Docker, the PHP CLI and Composer are assumed to be installed locally.
-The development stack runs containerized Caddy and PHP-FPM containers, but Composer is used as a task runner tool.
-
-```shell
-$ docker compose up -d
-$ composer install
-$ composer setup
-```
-
-After these commands the faucet will be available at `http://localhost:8080`, and set up with a regtest node with a wallet and 101 blocks already mined.
-
-The `composer.json` file also has tasks for generating bitcoin addresses, mining new blocks and running the linter and the test suite.
-
-To customize the Docker stack create a `compose.override.yml` at the root. On `docker compose up -d` it'll be automatically merged with `compose.yml`.
-Example, with custom environment variables and exposed Redis port for debugging:
-
-```yaml
-name: faucet
-
-services:
-  php-fpm:
-    env_file:
-      - .env
-  redis:
-    ports:
-      - 127.0.0.1:6379:6379
-```
-
-To customize the default environment variables create an `.env` file and set it up as an extra `env_file` for `php-fpm` as shown above.
-Example:
-
-```
-FAUCET_USE_CAPTCHA=1
-FAUCET_PASSWORD_BCRYPT_HASH='$2y$10$MyYyMkeWk2v4tvzA5lylyuWBsBXsvOfcGeCG61C9mVOdXDx1/BnyO'
-```
-
-Changing environment variables requires recreating the `php-fpm` container.
-
 ## Configuration
 
 ### Environment Variable Reference
@@ -99,9 +57,28 @@ The following environment variables can be used to configure your faucet instanc
 | `FAUCET_PASSWORD_BCRYPT_HASH`   | Bcrypt hash of the faucet's password                         | Read Password section         | No               |
 | `FAUCET_MEMPOOL_URL`            | Mempool URL where to show the instant payout transactions    | `https://mempool.example.com` | No               |
 
+### Password
+
+In order to avoid storing plain text secrets the faucet settings use a BCrypt hash instead of the password itself.
+
+Run the `bin/bcrypt.php` helper script to get a ready-made `FAUCET_PASSWORD_BCRYPT_HASH` definition from any given password.
+
+```shell
+$ php bin/bcrypt.php n0s3c0ndb3st
+FAUCET_PASSWORD_BCRYPT_HASH='$2y$10$cNZwPXN5N8.RUBrMNfZOhuT9ClWv0fWawSaxE4rTXbgTjrNVJTko2'
+```
+
 ### Transaction Batching
 
-TODO
+![batched payment example](docs/img/batch.png)
+
+Transaction batching instructs the faucet to withhold approved payouts to send them later on as a single transaction.
+To enable this mode, set `FAUCET_USE_BATCHING=1`.
+
+You also need to set up a cronjob that runs `bin/batch.php` at your preferred interval.
+Run `crontab -e` to edit the current user's crontab file.
+
+In [`docs/cron`](docs/cron/sample) there's an example on how to set up one such cronjob that runs every 15 minutes.
 
 ### Usage Limits
 
@@ -117,9 +94,53 @@ TODO
 
 TODO
 
-#### Apache
+### Development
+
+For development tasks Docker, the PHP CLI and Composer are assumed to be installed locally.
+The development stack runs containerized Caddy and PHP-FPM containers, but Composer is used as a task runner tool.
+
+```shell
+$ docker compose up -d
+$ composer install
+$ composer setup
+```
+
+After these commands the faucet will be available at `http://localhost:8080`, and set up with a regtest node with a wallet and 101 blocks already mined.
+
+The `composer.json` file also has tasks for fetching new addresses from the node's wallet, mining additional regtest blocks, running the test suite and applying the code linter:
+
+```shell
+$ composer lint
+$ composer mine
+$ composer newaddress
+$ composer test
+```
+
+To customize the Docker stack create a `compose.override.yml` at the root. On `docker compose up -d` it'll be automatically merged with `compose.yml`.
+Example, with custom environment variables and exposed Redis port for debugging:
+
+```yaml
+name: faucet
+
+services:
+  php-fpm:
+    env_file:
+      - .env
+  redis:
+    ports:
+      - 127.0.0.1:6379:6379
+```
+
+To customize the default environment variables create an `.env` file and set it up as an extra `env_file` for `php-fpm` as shown above.
+Example:
+
+```
+FAUCET_USE_CAPTCHA=1
+FAUCET_PASSWORD_BCRYPT_HASH='$2y$10$MyYyMkeWk2v4tvzA5lylyuWBsBXsvOfcGeCG61C9mVOdXDx1/BnyO'
+```
+
+Changing environment variables requires recreating the `php-fpm` container.
 
-TODO
 
 [@kallewoof]: https://github.com/kallewoof
 [bitcoin-faucet]: https://github.com/kallewoof/bitcoin-faucet

compose.yml

@@ -9,7 +9,7 @@ services:
       - 127.0.0.1:8080:80
     restart: on-failure
     volumes:
-      - ./etc/caddy/Caddyfile-dev:/etc/caddy/Caddyfile
+      - ./docs/caddy/Caddyfile-dev:/etc/caddy/Caddyfile
       - ./web:/var/www/signet-faucet/web
       - caddy_config:/config
       - caddy_data:/data
@@ -33,7 +33,7 @@ services:
     image: 1maa/bitcoin:v26.1.knots20240513
     restart: on-failure
     volumes:
-      - ./etc/knots/bitcoin.conf:/home/bitcoin/.bitcoin/bitcoin.conf
+      - ./docs/knots/bitcoin.conf:/home/bitcoin/.bitcoin/bitcoin.conf
       - knots_data:/home/bitcoin/.bitcoin
 
 volumes: