diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 984d248..fff827d 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -4,15 +4,16 @@ * Get Started - * [Start with Docker](getstarted/docker.md) - * [Dev Server Setup](getstarted/dev.md) + * [Start with Docker](getstarted/docker.md) + * [Dev Server Setup](getstarted/dev.md) * Reference - * [Environment Variables](reference/env.md) - * [Database Migration Guide](reference/db-migration.md) - * [Editing Documentation](reference/editing-docs.md) + * [Environment Variables](reference/env.md) + * [Database Migration Guide](reference/db-migration.md) + * [Altcha Implementation](reference/altcha.md) + * [Editing Documentation](reference/editing-docs.md) * Updates - * [v1.2.0](updates/1.2.0.md) \ No newline at end of file + * [v1.2.0](updates/1.2.0.md) \ No newline at end of file diff --git a/docs/getstarted/dev.md b/docs/getstarted/dev.md index e9200bf..03334d3 100644 --- a/docs/getstarted/dev.md +++ b/docs/getstarted/dev.md @@ -29,11 +29,20 @@ bunx auth secret ``` -5. **Configure environment variables** +5. **Generate Altcha token** + + If you plan to use the signup forms, you will need to use Altcha, a private proof-of-work CAPTCHA. All you need to do is execute the script below, and it will be written to your `.env` or `.env.local`. + + ```bash + $ bun tools/hmac.ts + Successfully wrote ALTCHA_SECRETKEY to .env.local + ``` + +6. **Configure environment variables** Following the environment variables section of this README, update your newly created `.env.local` file with your configuration. -6. **Initialize Prisma** +7. **Initialize Prisma** Because `web` uses a database for storing Git link statuses (and other things to come), you will need to initialize the SQLite database. @@ -45,7 +54,7 @@ bunx prisma migrate dev --name init ``` -7. **Start dev server** +8. **Start dev server** ```bash bun dev diff --git a/docs/getstarted/docker.md b/docs/getstarted/docker.md index 0c4b067..d479716 100644 --- a/docs/getstarted/docker.md +++ b/docs/getstarted/docker.md @@ -36,11 +36,20 @@ A Docker setup requires both Docker *and* Docker Compose. bunx auth secret ``` -4. **Configure environment variables** +4. **Generate Altcha token** + + If you plan to use the signup forms, you will need to use Altcha, a private proof-of-work CAPTCHA. All you need to do is execute the script below, and it will be written to your `.env` or `.env.local`. + + ```bash + $ bun tools/hmac.ts + Successfully wrote ALTCHA_SECRETKEY to .env.local + ``` + +5. **Configure environment variables** Following the environment variables section of this README, update your newly created `.env.local` file with your configuration. -5. **Initialize Prisma** +6. **Initialize Prisma** Because `web` uses a database for storing Git link statuses (and other things to come), you will need to initialize the SQLite database. @@ -52,11 +61,11 @@ A Docker setup requires both Docker *and* Docker Compose. bunx prisma migrate dev --name init ``` -6. **Setup environment variables** +7. **Setup environment variables** Now is the time to go to the "Environment Variables" section and configure them in your `.env.local` file. -7. **Bring the container up** +8. **Bring the container up** ```bash docker compose up -d --build @@ -66,7 +75,7 @@ A Docker setup requires both Docker *and* Docker Compose. You may customize the container with the included `docker-compose.yml` file if needed. Your server will start on port `3019` by default. We suggest using a reverse proxy to serve the site on a domain. -8. **Complete Setup** +9. **Complete Setup** If you would like to host the entire LibreCloud frontend and backend, you will also need to set up the following repositories and edit this project to work with *your* setup. diff --git a/docs/reference/altcha.md b/docs/reference/altcha.md new file mode 100644 index 0000000..3f307fe --- /dev/null +++ b/docs/reference/altcha.md @@ -0,0 +1,47 @@ +# Altcha Implementation + +Altcha is a privacy-friendly CAPTCHA alternative that's used in the LibreCloud signup form to verify that users are not bots. This doc explains the implementation, setup, and configuration of Altcha with LibreCloud. + +## Basic Overview + +Altcha works by serving a proof-of-work-based CAPTCHA which doesn't require any fingerprinting/data collection. Our implementation does not use their API, and instead uses an endpoint, `/api/captcha/create`. The setup of this is nearly automatically. + +## Components + +1. **Widget** (`components/custom/Altcha.tsx`) + + This component renders the Altcha widget for use in pages. + +2. **API Endpoint** (`app/api/captcha/create/route.ts`) + + This endpoint generates the challenges with the altcha library. + +3. **Token Validation** (`lib/utils.ts`) + + The utils file provides verification for submitted tokens from the client. This is what gets implemented into an API route which needs to be protected by Altcha. You can see an example of this in `app/api/users/create/route.ts`, which connects to `app/account/signup/page.tsx`. + +## Setup + +### Environment Variables + +To use Altcha, you need to set the following environment variable: + +```text +ALTCHA_SECRETKEY= +``` + +#### Automatic Setup + +You should generate this with the provided `tools/hmac.ts` script. This is an important part of setup for people who want to take advantage of the signup forms. + +The script requires the existance of an `.env` or `.env.local` file. You should have had this created when you setup Auth.js with `bunx auth secret`. + +Execute the script like so: + +```bash +bun tools/hmac.ts +``` + +## Debug Mode + +The Altcha widget is in debug mode when `NODE_ENV` is set to `"development"`. This is nice for testing but you should disable it in production. diff --git a/docs/reference/env.md b/docs/reference/env.md index a9dd18c..582e9db 100644 --- a/docs/reference/env.md +++ b/docs/reference/env.md @@ -17,6 +17,23 @@ With these variables, you can disable entire parts of the dashboard, such as reg | NEXT_PUBLIC_TELEGRAM_CHANNEL_URL | Changes the default Telegram channel link in Support dash | String - `https://t.me/...` | | NEXT_PUBLIC_TELEGRAM_GROUP_URL | Changes the default Telegram group link in Support dash | String - `https://t.me/...` | +## Altcha + +Altcha is a privacy-friendly CAPTCHA alternative we use for bot traffic mitigation and anti-spam. +It requires a secret key for generating and verifying challenges. The rest is handled by the API. + +| Environment Variable | Description | Example | +|----------------------|-----------------------------------------------------------|----------------------------------------| +| ALTCHA_SECRETKEY | Secret key for generating and verifying Altcha challenges | N/A | + +### Automatic Secret Key Setup + +We've included an automatic setup script for your Altcha secret key. It generates and writes a secure token to your `.env` or `.env.local` file. You can execute this script like so: + +```bash +bun tools/hmac.ts +``` + ## Authentik We use [Auth.js](https://authjs.dev) to provide authentication for users through Authentik.