Skip to content

πŸ“š The open-source, offline-first Notion, Obsidian & Confluence alternative. Advanced Markdown, multi-tenant teams, OIDC/SSO, and local S3 backups. Deploy in one command.

fix(docs): update README with synthesis of docs

Smaug6739b4499cbe1377
diff --git a/docs/README.md b/docs/README.md
index ab983359..b76b27d6 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,62 +1,272 @@
-# Nuxt Docs Template
+# Alexandrie Setup Guide
-[![Nuxt UI](https://img.shields.io/badge/Made%20with-Nuxt%20UI-00DC82?logo=nuxt&labelColor=020420)](https://ui.nuxt.com)
+This guide explains how to set up, configure, and deploy the Alexandrie stack.
-Use this template to build your own documentation with [Nuxt UI](https://ui.nuxt.com) quickly.
+It covers both **local development** and **production deployment**, including how to configure environment variables, connect the different services, and handle HTTPS with a reverse proxy.
-- [Live demo](https://docs-template.nuxt.dev/)
-- [Documentation](https://ui.nuxt.com/docs/getting-started/installation/nuxt)
+---
-<a href="https://docs-template.nuxt.dev/" target="_blank">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://ui.nuxt.com/assets/templates/nuxt/docs-dark.png">
- <source media="(prefers-color-scheme: light)" srcset="https://ui.nuxt.com/assets/templates/nuxt/docs-light.png">
- <img alt="Nuxt Docs Template" src="https://ui.nuxt.com/assets/templates/nuxt/docs-light.png">
- </picture>
-</a>
+## Overview of the Stack
+
+The Alexandrie stack consists of four main services, defined in the `docker-compose.yml` file:
+
+| Service | Description |
+| ------------ | ------------------------------------------------------------------------------ |
+| **MySQL** | Relational database used to store user data and metadata. |
+| **RustFS** | S3-compatible object storage used for file and media storage. |
+| **Backend** | The Go-based API server providing authentication, storage, and access control. |
+| **Frontend** | A Nuxt 4 web app that communicates with the backend via REST API. |
+
+All services are connected through a dedicated Docker network (`alexandrie-network`).
+
+---
## Quick Start
-```bash [Terminal]
-npm create nuxt@latest -- -t ui/docs
+For local testing, you can run Alexandrie directly using the provided `docker-compose.yml`:
+
+Download the `docker-compose.yml` file from the repository: [https://github.com/Smaug6739/Alexandrie/blob/main/docker-compose.yml](https://github.com/Smaug6739/Alexandrie/blob/main/docker-compose.yml) and run:
+
+```bash
+docker compose up
```
-## Deploy your own
+Once the containers are running:
-[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-name=docs&repository-url=https%3A%2F%2Fgithub.com%2Fnuxt-ui-templates%2Fdocs&demo-image=https%3A%2F%2Fui.nuxt.com%2Fassets%2Ftemplates%2Fnuxt%2Fdocs-dark.png&demo-url=https%3A%2F%2Fdocs-template.nuxt.dev%2F&demo-title=Nuxt%20Docs%20Template&demo-description=A%20documentation%20template%20powered%20by%20Nuxt%20Content.)
+- Frontend β†’ http://localhost:8200
+- Backend API β†’ http://localhost:8201
+- Object Storage (RustFS) β†’ http://localhost:9000
-## Setup
+> [!NOTE]
+> No default account is created. You can register a new user directly from the frontend.
+> If you want to make it admin of application, add the account ID to the `ADMIN_ACCOUNTS` variable.
-Make sure to install the dependencies:
+## Configuration (Environment Variables)
-```bash
-pnpm install
+To customize the setup (ports, domains, security, feature flags, production deployment), you can create a `.env` file next to `docker-compose.yml`.
+
+The `.env` file template can be found here: [https://github.com/Smaug6739/Alexandrie/blob/main/.env.example](https://github.com/Smaug6739/Alexandrie/blob/main/.env.example)
+
+Only the variables defined in `.env.example` are officially supported.
+
+### 1. Public URLs & Global Access
+
+```env
+FRONTEND_URL=http://localhost:8200
+API_URL=http://localhost:8201
+CDN_URL=http://localhost:9005
+
+CDN_ENDPOINT=/alexandrie/
```
-## Development Server
+These variables define how clients (browsers) reach your services.
-Start the development server on `http://localhost:3000`:
+- `FRONTEND_URL`: The public URL for the frontend service.
+- `API_URL`: The public URL for the backend API service.
+- `CDN_URL`: The public URL for the object storage service (RustFS).
+- `CDN_ENDPOINT`: The path prefix under which files are exposed. You probably want to keep this as /alexandrie/ to match the bucket name, change it only if you changed the bucket name or if you have configured a reverse proxy path.
+ Final URL are constructed as: `<CDN_URL><CDN_ENDPOINT><object-path>`
+ If you have a problem with files URL just open devtools in your browser and check the actual URL used to load files and then adjust these variables accordingly.
-```bash
-pnpm dev
+### 2. Application Feature Flags
+
+```env
+CONFIG_DISABLE_LANDING=false
+CONFIG_DISABLE_SIGNUP=false
+CONFIG_DISABLE_NATIVE_LOGIN=false
+CONFIG_OIDC_PROVIDER_AUTO_REDIRECT=""
+CONFIG_HIDE_NATIVE_LOGIN_FORM=false
```
-## Production
+These variables control specific features of the application (useful for private deployments, internal tools etc.).
-Build the application for production:
+- `CONFIG_DISABLE_LANDING`: If set to `true`, the landing page is disabled, and users are redirected to the login page. The default is `false`.
+- `CONFIG_DISABLE_SIGNUP`: If set to `true`, new user registrations are disabled (in frontend + backend for security). The default is `false`.
+- `CONFIG_DISABLE_NATIVE_LOGIN`: If set to `true`, the native username/password login method is disabled. This is useful if you want to enforce OIDC or other external authentication methods. The default is `false`.
+- `CONFIG_HIDE_NATIVE_LOGIN_FORM`: If set to `true`, the native username/password login method is hidden. This is useful if you want to enforce OIDC or other external authentication methods but without setting up `CONFIG_OIDC_PROVIDER_AUTO_REDIRECT`. The default is `false`. Recommended to use in conjunction with `CONFIG_DISABLE_NATIVE_LOGIN`.
+- `CONFIG_OIDC_PROVIDER_AUTO_REDIRECT`: Provide a string that matches the provider name of one of your OIDC providers, if provided the user is automatically redirected to the OIDC login when landing on the login page.
-```bash
-pnpm build
+### 3. Backend API β€” Runtime & Security
+
+```env
+BACKEND_EXTERNAL_PORT=8201
+COOKIE_DOMAIN=localhost:8200
+ALLOW_UNSECURE=true
+JWT_SECRET=your-secure-jwt-secret-key-change-this-in-production
+ADMIN_ACCOUNTS=id1,id2,id3
```
-Locally preview production build:
+These variables configure the backend API service.
-```bash
-pnpm preview
+- `BACKEND_EXTERNAL_PORT`: The port exposed on your host machine for the Backend API service.
+- `COOKIE_DOMAIN` (IMPORTANT): This variable defines where authentication cookies are valid.
+ It should match with the common domain used by both frontend and backend services.
+ Example: If your frontend is at `frontend.yourdomain.com` and your backend API is at `api.yourdomain.com`, then set `COOKIE_DOMAIN=yourdomain.com`.
+ **Rules:**
+ - Must match with the highest common domain between the frontend and the backend. See #286 for more details.
+ - Must NOT include protocol (http:// or https://)
+ - If misconfigured, login will appear to work but users will be instantly logged out
+- `ALLOW_UNSECURE`: If set to `true`, HTTP connections are allowed (useful for local and dev). In production, it is recommended to set this to `false` to enforce HTTPS.
+- `JWT_SECRET`: Secret key used to sign JWT tokens. You should change this to a random long string correcly generated (with openssl or similar) in production for security. Changing this value will invalidate all existing sessions.
+- `ADMIN_ACCOUNTS`: Comma-separated list of user IDs that should have admin privileges (e.g., `1,2,3`). Optional.
+
+### 4. Database β€” MySQL
+
+```env
+MYSQL_EXTERNAL_PORT=3307
+MYSQL_DATABASE=alexandrie
+MYSQL_USER=alexandrie
+MYSQL_PASSWORD=password
+MYSQL_ROOT_PASSWORD=rootpassword
+```
+
+These variables configure the MySQL database service.
+
+- `MYSQL_EXTERNAL_PORT`: The port exposed on your host machine for the MySQL service.
+- `MYSQL_DATABASE`: The name of the default database created for Alexandrie.
+- `MYSQL_USER`: The username for the default Alexandrie database user.
+- `MYSQL_PASSWORD`: The password for the default Alexandrie database user.
+- `MYSQL_ROOT_PASSWORD`: The password for the MySQL root user.
+
+### 5. Object Storage β€” S3 (RustFS / MinIO-compatible) (optional, leave empty to disable)
+
+```env
+RUSTFS_EXTERNAL_PORT=9005
+
+RUSTFS_ACCESS_KEY=alexandrie-key
+RUSTFS_SECRET_KEY=alexandrie-secret
+
+MINIO_BUCKET=alexandrie
+```
+
+These variables configure the RustFS object storage service.
+
+- `RUSTFS_EXTERNAL_PORT`: The port exposed on your host machine for the RustFS service.
+- `RUSTFS_ACCESS_KEY`: The access key for the RustFS S3-compatible API.
+- `RUSTFS_SECRET_KEY`: The secret key for the RustFS S3-compatible API.
+- `MINIO_BUCKET`: The name of the default bucket created for Alexandrie. Note that this bucket name should match the `CDN_ENDPOINT` variable in the backend configuration. By default, it is set to `alexandrie` and the backend will create `alexandrie` and `alexandrie-backups` buckets.
+
+### 6. Email β€” SMTP (optional)
+
+```env
+SMTP_HOST=
+SMTP_MAIL=
+SMTP_PASSWORD=
+SMTP_MAIL_FROM= # Optional
+```
+
+Used only for password reset emails. Leave empty to disable email features (default).
+
+- `SMTP_HOST`: The SMTP server host.
+- `SMTP_MAIL`: The email address used to send emails.
+- `SMTP_PASSWORD`: The password for the SMTP email account.
+- `SMTP_MAIL_FROM` The email adress used to send messages (optional, default same as `SMTP_MAIL`)
+
+### 7. Frontend β€” Nuxt
+
+```env
+FRONTEND_EXTERNAL_PORT=8200
+```
+
+The port exposed on the host for the frontend container.
+
+In production, this is usually only accessed by a reverse proxy.
+
+## Production Deployment Notes
+
+In production, you should:
+
+- NOT expose MySQL or RustFS directly
+- Use a reverse proxy (Nginx, Traefik, Caddy)
+- Terminate HTTPS at the proxy
+
+## Additional Configuration & Advanced Setup
+
+### Custom configuations - config.toml
+
+For advanced configuration options for backend you can create your own `config.toml` file with the same structure as the default one (in `backend/config.toml`) and add the following environment variable to your `.env` file:
+
+```env
+CONFIG_PATH=./config.toml # Path to your custom config.toml file
+```
+
+This allows you to customize advanced settings not covered by environment variables (such as default values, logging levels, supported files etc).
+
+### OIDC Integration
+
+Open ID Connect (OIDC) is supported since version 8.5.0. You can setup up to 10 providers using environment variables to the backend.
+
+First you have to generate client ID and client secret from your provider (refer to their doc or ask questions in discussions / discord)
+
+Then you have to configure the redirect URI (in the provider interface with this value): `https://your-alexandrie-frontend/login/oidc/callback`
+
+To config a provider you have to fill 4 variables:
+
+```env
+OIDC_{i}_CONFIG_URL=https://yourdomain.com/.well-known/openid-configuration
+OIDC_{i}_CLIENT_ID=
+OIDC_{i}_CLIENT_SECRET=
+OIDC_{i}_PROVIDER_NAME= # e.g. Google, Discord, Microsoft...
+```
+
+_Replace `{i}` with a number between 1 to 10_
+
+To setup these variables to your configuration you have to edit the `docker-compose.yml` and add variables to the backend config (direct values or a reference to your env file) like this for example:
+
+```yml
+OIDC_1_CONFIG_URL: ${OIDC_1_CONFIG_URL}
+OIDC_1_CLIENT_ID: ${OIDC_1_CLIENT_ID}
+OIDC_1_CLIENT_SECRET: ${OIDC_1_CLIENT_SECRET}
+OIDC_1_PROVIDER_NAME: ${OIDC_1_PROVIDER_NAME}
+```
+
+### S3 / Minio β€” TLS, HTTPS and Custom Certificate Authorities
+
+Alexandrie connects to the S3-compatible storage (RustFS / MinIO...) using an internal backend client.
+This client supports HTTPS, custom certificate authorities (CA), and explicit TLS configuration.
+
+This section explains how TLS is handled and how to configure it correctly.
+
+#### HTTPS vs HTTP (MINIO_SECURE)
+
+```env
+MINIO_SECURE=true|false
+```
+
+This variable controls whether HTTPS (TLS) is used at all when the backend connects to the S3 endpoint. It must explicitly match how your S3 server is exposed.
+
+- `true` β†’ HTTPS is used (default)
+- `false` β†’ HTTP is used (no TLS)
+
+#### Custom Certificate Authorities (MINIO_CA_PATH)
+
+If your S3 endpoint uses a certificate signed by an internal or private certificate authority, you must explicitly provide this CA to the backend.
+
+```env
+MINIO_CA_PATH=/path/to/ca-certificate.pem
+```
+
+- The file must contain the CA certificate (root or intermediate), in PEM format
+- This CA will be added to the system trust store used by the S3 client
+- This is the recommended and secure way to handle internal PKI
+
+> [!NOTE]
+> if you are using docker containers, you must mount this file into the backend container using a volume in `docker-compose.yml`.
+
+_TLS Verification Bypass (Not Recommended)_
+
+```env
+MINIO_INSECURE_TLS=true|false
```
-Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
+This option disables TLS certificate verification while still using HTTPS.
-## Renovate integration
+- The connection remains encrypted
+- Certificate validation (CA + hostname) is skipped
-Install [Renovate GitHub app](https://github.com/apps/renovate/installations/select_target) on your repository and you are good to go.
+> [!WARNING]
+> This option should only be used for:
+>
+> - temporary debugging
+> - local testing environments
+> - It is not recommended for production use.