diff --git a/README.md b/README.md index 16b2971..ec0a1ef 100644 --- a/README.md +++ b/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,46 @@ 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 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. -TODO [@kallewoof]: https://github.com/kallewoof [bitcoin-faucet]: https://github.com/kallewoof/bitcoin-faucet diff --git a/compose.yml b/compose.yml index a32b0b1..1ef8e1b 100644 --- a/compose.yml +++ b/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: diff --git a/etc/caddy/Caddyfile-dev b/docs/caddy/Caddyfile-dev similarity index 100% rename from etc/caddy/Caddyfile-dev rename to docs/caddy/Caddyfile-dev diff --git a/etc/caddy/Caddyfile-prod b/docs/caddy/Caddyfile-prod similarity index 100% rename from etc/caddy/Caddyfile-prod rename to docs/caddy/Caddyfile-prod diff --git a/etc/cron/sample b/docs/cron/sample similarity index 100% rename from etc/cron/sample rename to docs/cron/sample diff --git a/docs/img/batch.png b/docs/img/batch.png new file mode 100644 index 0000000..44054c0 Binary files /dev/null and b/docs/img/batch.png differ diff --git a/etc/knots/bitcoin.conf b/docs/knots/bitcoin.conf similarity index 100% rename from etc/knots/bitcoin.conf rename to docs/knots/bitcoin.conf