diff --git a/README.md b/README.md index 12414d4..029bb6a 100644 --- a/README.md +++ b/README.md @@ -61,17 +61,21 @@ A Docker setup requires both Docker *and* Docker Compose. bunx prisma migrate dev --name init ``` -6. **Bring the container up** +6. **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** ```bash - docker compose up -d + docker compose up -d --build ``` Please note: `sudo` may be required. 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. -7. **Complete Setup** +8. **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/.nojekyll b/docs/.nojekyll new file mode 100644 index 0000000..e69de29 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..4b82c0b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,19 @@ + + +# Welcome to LibreCloud Docs + +LibreCloud's web repository is a Next.js web application which serves as out frontend and dashboard for end users of LibreCloud. This documentation will guide you through setting up and developing this interface. + +We have made every effort to update and review the documentation and this stands to be the best resource for setting up `web`. + +## Requirements + +LibreCloud is not one piece of software. It is a bridge between FOSS and a this frontend. This project assumes you have a setup almost identical to that of LibreCloud. With our instructions and some Google searches, you should have very few problems getting setup. + +This frontend is optomized for a Linux environment. While support may vary from distro-to-distro, support is prioritized for Ubuntu. + +You will need to setup the following services with Docker, and route them properly, based on our [Environment Variable](reference/env.md) requirements. Over time, this will become more flexible. + +## Get Started + +For the best experience, we suggest you use a [Docker setup](getstarted/docker.md) in production, and a [Dev environment](getstarted/dev.md) while testing/making changes. \ No newline at end of file diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 0000000..8f70552 --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,13 @@ +LibreCloud + +* [Home](/) + +* Get Started + + * [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) \ No newline at end of file diff --git a/docs/getstarted/dev.md b/docs/getstarted/dev.md new file mode 100644 index 0000000..e9200bf --- /dev/null +++ b/docs/getstarted/dev.md @@ -0,0 +1,52 @@ +# Dev Server Setup + +1. **Install Bun if you haven't already** + + Bun is a fast JavaScript runtime, which we prefer over `npm`. These instructions will be written for Bun, but could be adapted to `npm` or `yarn` if needed. + + ```bash + curl -fsSL https://bun.sh/install | bash + ``` + +2. **Clone the repo** + + ```bash + git clone https://git.pontusmail.org/librecloud/web.git + cd web + ``` + +3. **Install dependencies** + + ```bash + bun install + ``` + +4. **Generate auth secret** + + This step is relatively painless. 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. + + A `schema.prisma` file has been provided to make this easy. + + This can be done by executing: + + ```bash + bunx prisma migrate dev --name init + ``` + +7. **Start dev server** + + ```bash + bun dev + ``` \ No newline at end of file diff --git a/docs/getstarted/docker.md b/docs/getstarted/docker.md new file mode 100644 index 0000000..0c4b067 --- /dev/null +++ b/docs/getstarted/docker.md @@ -0,0 +1,75 @@ +# Start with Docker + +A Docker setup requires both Docker *and* Docker Compose. + +1. **Install Bun if you haven't already** + + Bun is a fast JavaScript runtime, which we prefer over `npm`. These instructions will be written for Bun, but could be adapted to `npm` or `yarn` if needed. + + ```bash + curl -fsSL https://bun.sh/install | bash + ``` + +2. **Fetch needed file(s)** + + Pick your preferred option to get the file(s) needed for Docker. Either option is fine, although Git is arguably the best option. + + **Option One:** Clone Git Repo + + ```bash + git clone https://git.pontusmail.org/librecloud/web.git + ``` + + **Option Two:** Download Compose file only + + ```bash + wget https://git.pontusmail.org/librecloud/web/raw/branch/main/docker-compose.yml + ``` + + You may have to install `wget`, or you could use `curl` instead. + +3. **Generate auth secret** + + This step is relatively painless. 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** + + 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. **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** + + ```bash + docker compose up -d --build + ``` + + Please note: `sudo` may be required. + + 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** + + 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. + + * [mail-connect](https://git.pontusmail.org/librecloud/mail-connect) + * [docker-mailserver](https://github.com/docker-mailserver/docker-mailserver) \ No newline at end of file diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..f9a1a95 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,23 @@ + + + + + Document + + + + + + +
+ + + + + diff --git a/docs/reference/db-migration.md b/docs/reference/db-migration.md new file mode 100644 index 0000000..034896d --- /dev/null +++ b/docs/reference/db-migration.md @@ -0,0 +1,10 @@ +# Database Migration Guide + +In case of an update to `prisma/schema.prisma` in this repo, you should run the below command to migrate the old database. + +Each update to this file is guaranteed to work with the previous version of the file to ensure maximum compatibility. While every effort has been made to ensure compatibility, we are not responsible for any data loss. + +```bash +npx prisma migrate dev --name update-schema # Migrate +npx prisma migrate deploy # Deploy +``` \ No newline at end of file diff --git a/docs/reference/env.md b/docs/reference/env.md new file mode 100644 index 0000000..722aa96 --- /dev/null +++ b/docs/reference/env.md @@ -0,0 +1,66 @@ +# 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 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 its 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 its 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) | + +## Cloudflare + +We use Cloudflare Turnstile for detecting bots and automated scripts attempting to abuse our services. We chose it because it's the perfect balance of security and convenience for users. It was also the most preferred option in the [poll we ran on my Telegram channel](https://t.me/pontushub/457). + +You can get the keys you need for Cloudflare Turnstile [here](https://www.cloudflare.com/application-services/products/turnstile/). It's very plug and play. + +If you would like to simply test or bypass Cloudflare Turnstile, you can use one of the site keys provided [here](https://developers.cloudflare.com/turnstile/troubleshooting/testing/) instead of your own. + +| Environment Variable | Description | Example | +|------------------------|-------------------------------------------|---------------------------------------| +| NEXT_PUBLIC_CF_SITEKEY | Cloudflare Turnstile site key (public) | `1x00000000000000000000AA` | +| CF_SECRETKEY | Cloudflare Turnstile secret key (private) | `0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX` | \ No newline at end of file