Aidan
11d2e02f89
All checks were successful
Build and Push Nightly CI Image / build_and_push (push) Successful in 4s
Build and Push Docker Image / build_and_push (push) Successful in 4s
184 lines
7.9 KiB
Markdown
184 lines
7.9 KiB
Markdown
# web
|
|
|
|
|
|
[](http://creativecommons.org/publicdomain/zero/1.0/)
|
|
[](https://git.pontusmail.org/librecloud/web/actions/?workflow=docker.yaml)
|
|
[](https://git.pontusmail.org/librecloud/web/actions/?workflow=ci.yaml)
|
|
|
|
LibreCloud's website, dashboard, and API
|
|
|
|
## Docker Instructions
|
|
|
|
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. 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
|
|
```
|
|
|
|
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**
|
|
|
|
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.
|
|
|
|
* [mail-connect](https://git.pontusmail.org/librecloud/mail-connect)
|
|
* [docker-mailserver](https://github.com/docker-mailserver/docker-mailserver)
|
|
|
|
## Dev Server Instructions
|
|
|
|
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. 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.
|
|
|
|
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
|
|
```
|
|
|
|
## 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
|
|
|
|
* [X] Add documentation on .env
|
|
* [ ] Implement security scans
|
|
* [ ] Ratelimiting on API
|