web

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.

   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

   git clone https://git.pontusmail.org/librecloud/web.git

   Option Two: Download Compose file only

   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.

   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:

   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

   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
   • 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.

   curl -fsSL https://bun.sh/install | bash

2. Clone the repo

   git clone https://git.pontusmail.org/librecloud/web.git
   cd web

3. Install dependencies

   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.

   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:

   bunx prisma migrate dev --name init

7. Start dev server

   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 the listed environment variables.

Authentik

We use Auth.js 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.

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.

You can get the keys you need for Cloudflare Turnstile here. 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 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

Troubleshooting

Performing a database migration

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.

npx prisma migrate dev --name update-schema # Migrate
npx prisma migrate deploy # Deploy

To-Do

• Add theme switcher to home page
• Implement security scans
• Rate-limiting on API