From 11d2e02f89fc50c8113fbd486ba22f9e664b20ea Mon Sep 17 00:00:00 2001 From: Aidan Date: Wed, 19 Feb 2025 22:46:25 -0500 Subject: [PATCH] docs: add env documentation, update installation instructions --- README.md | 93 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 88 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index a155cf1..93f07b0 100644 --- a/README.md +++ b/README.md @@ -37,7 +37,28 @@ A Docker setup requires both Docker *and* Docker Compose. You may have to install `wget`, or you could use `curl` instead. -3. **Bring the container up** +3. **Generate auth secret** + + This step is relatively painless. Simply execute the below command to generate a `.env.local` file with an `AUTH_SECRET`. + + ```bash + bunx auth secret + ``` + +4. **Configure environment variables** + + Following the environment variables section of this README, update your newly created `.env.local` file with your configuration. + +5. **Initialize Prisma (optional)** + + Because `web` uses a database for storing Git link statuses (and other things to come), you will need to initialize the SQLite database. However, if you are using Docker Compose, a database has already been generated in the container image, and is blank. + + If you have a reason to initialize Prisma now, feel free to execute: + + ```bash + bunx prisma migrate dev --name init + +6. **Bring the container up** ```bash docker compose up -d @@ -47,7 +68,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. -4. **Complete Setup** +7. **Complete Setup** If you would like to host the entire LibreCloud frontend and backend, you will also need to setup the following repositories and edit this project to work with *your* setup. @@ -77,7 +98,19 @@ A Docker setup requires both Docker *and* Docker Compose. bun install ``` -4. **Initialize Prisma** +4. **Generate auth secret** + + This step is relatively painless. Simply execute the below command to generate a `.env.local` file with an `AUTH_SECRET`. + + ```bash + bunx auth secret + ``` + +5. **Configure environment variables** + + Following the environment variables section of this README, update your newly created `.env.local` file with your configuration. + +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. @@ -89,12 +122,62 @@ A Docker setup requires both Docker *and* Docker Compose. bunx prisma migrate dev --name init ``` -5. **Start dev server** +7. **Start dev server** ```bash bun dev ``` +## Environment Variables + +At the time of writing, LibreCloud is not in the state of perfection, and as such we are expecting that you have a setup exact to ours. While this will change in the future, we still suggest that provide all of the listed environment variables. + +### Authentik + +We use [Auth.js](https://authjs.dev) to provide authentication for users through Authentik. To do this, you will need to create a new OAuth2 provider in Authentik and put it's configuration in your `.env` file. + +If you need more help doing this, there is a fantastic guide [on Authentik's wiki](https://docs.goauthentik.io/docs/add-secure-apps/providers/oauth2/). + +| Environment Variable | Description | Example | +|-----------------------|---------------------------------------------------------|-------------------------------------------------| +| AUTH_AUTHENTIK_ID | (Auth.js) OAuth2 Provider - Client ID | `UHEkjdUIqi938hUIEijdkWZiudhIUshefIJIo8u3u` | +| AUTH_AUTHENTIK_SECRET | (Auth.js) OAuth2 Provider - Client Secret | [long string] | +| AUTH_AUTHENTIK_ISSUER | (Auth.js) OAuth2 Provider - OpenID Configuration Issuer | `http://authentik.local/application/o/example/` | +| AUTHENTIK_API_KEY | API key for authenticating with Authentik's API | N/A | +| AUTHENTIK_API_URL | Authentik's API endpoint URL | `http://authentik.local/api/v3` | + +### Gitea + +Next, you will need to configure `web` with your Gitea instance. Create a new access token in your Gitea user settings (), and input the key you receive, as well as the URL of your instance, and the API URL. You can find a link to the API and it's endpoint URL on the footer. + +| Environment Variable | Description | Example | +|----------------------|-----------------------------------------------|--------------------------------------------| +| GITEA_API_URL | Your Gitea instance API endpoint (see footer) | `http://gitea.local/api/v1` | +| GITEA_API_KEY | Access Token created in user settings | `0000000000000000000000000000000000000000` | +| GITEA_URL | Your Gitea instance URL | `http://gitea.local` | + +### mail-connect + +mail-connect, another project by LibreCloud, is a bridge from `docker-mailserver` to an API. It talks to the container via a Docker socket, but you will need to tell `web` where to find your mailserver API. + +Keep in mind, this endpoint should **NOT** be public, and `web` should be the only authorized user of the API, unless you know what you're doing. There is zero authentication. + +| Environment Variable | Description | Example | +|----------------------|------------------------------|-----------------------| +| MAIL_CONNECT_API_URL | URL of your mail-connect API | `http://localhost:4200` | + +### Auth.js + +We suggest starting by allowing Auth.js + +| Environment Variable | Description | Example | +|----------------------|---------------------------------------------------|-----------------------------------------------------------------------| +| AUTH_SECRET | Generated during `.env.local` creation | `R98/+7HbakYa73YHbooAND+nzae8RaudOdq8Uab/suE=` | +| AUTH_TRUST_HOST | Required, should always be set to `true` | `true` | +| NEXTAUTH_URL | The URL LibreCloud will be publicly accessible at | `http://localhost:3000` (testing), `https://example.com` (production) | + ## To-Do -* [ ] Add documentation on .env +* [X] Add documentation on .env +* [ ] Implement security scans +* [ ] Ratelimiting on API