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.

docs: documentation for MINIO_CA_PATH and MINIO_INSECURE_TLS variables

Smaug6739a7ade8087fcc
diff --git a/docs/FAQ.md b/docs/FAQ.md
new file mode 100644
index 00000000..ee7c4fdb
--- /dev/null
+++ b/docs/FAQ.md
@@ -0,0 +1,89 @@
+# FAQ β€” Common Issues & Troubleshooting
+
+## I am instantly logged out after logging in (login loop)
+
+**Symptoms**
+
+- Login succeeds (no error message).
+- You are redirected correctly.
+- You are immediately logged out or returned to the login page.
+- Refreshing the page shows you as unauthenticated.
+
+**Cause**
+
+This is usually caused by a misconfiguration of the `COOKIE_DOMAIN` environment variable in the backend service.
+
+**Common mistakes**
+
+- Including protocol (http:// or https://) in `COOKIE_DOMAIN`.
+- Setting `COOKIE_DOMAIN` to a subdomain that does not match both frontend and backend domains.
+- Setting `COOKIE_DOMAIN` to a domain that does not match the actual domain used to access the services.
+
+**Correct configuration examples**
+
+- If your frontend is at `frontend.yourdomain.com` and your backend API is at `api.yourdomain.com`, then set `COOKIE_DOMAIN=yourdomain.com`.
+- If your frontend is at `frontend.subdomain.yourdomain.com` and your backend API is at `api.subdomain.yourdomain.com`, then set `COOKIE_DOMAIN=subdomain.yourdomain.com`.
+- If your frontend is at `yourdomain.com` and your backend API is at `api.yourdomain.com`, then set `COOKIE_DOMAIN=yourdomain.com`.
+
+## Files are uploaded but cannot be accessed
+
+**Symptoms**
+
+- File uploads succeed without errors.
+- You show files as uploaded in the frontend (for example on the cdn page, in the datatable or in cards)
+- When trying to access the files, you get 404 errors or broken links.
+
+**Cause**
+This is usually caused by a misconfiguration of the `CDN_URL` and/or `CDN_ENDPOINT` environment variables in the backend service.
+
+**Common mistakes**
+
+- `CDN_URL` not matching the actual URL used to access to your S3 server storage (for example when using a reverse proxy with a different domain or path)
+- `CDN_ENDPOINT` not matching the bucket name or the path used in the reverse proxy.
+
+**Correct configuration examples**
+
+- If your RustFS S3 server is accessible at `http://cdn.yourdomain.com`, then set:
+ - `CDN_URL=http://cdn.yourdomain.com`
+ - `CDN_ENDPOINT=/alexandrie/` (/alexandrie/ is the default bucket name, change it only if you changed the bucket name or if your reverse proxy uses a different path)
+- If your RustFS S3 server is accessible at `http://yourdomain.com/files/`, then set:
+ - `CDN_URL=http://yourdomain.com`
+ - `CDN_ENDPOINT=/files/` (change /files/ to match the path used in your reverse proxy or the bucket name)
+
+Test the right url in your browser by combining `CDN_URL`, `CDN_ENDPOINT` and the object path (you can get the object path from the frontend interface, for example in the cdn page with devtools or by copying the link).
+
+## I have errors with backup system or minio client
+
+**Symptoms**
+
+- Backup creation fails with errors related to link generation with S3 or MinIO (example: Failed to generate download URL: XML syntax error on line 1: attribute name without = in element)
+
+**Cause**
+This is usually caused if you have an incorrect value for endpoint of public signer with minio client in the backend service.
+
+**Correct configuration examples**
+
+- If your RustFS S3 server is accessible at `http://cdn.yourdomain.com`, then set: `CDN_URL=http://cdn.yourdomain.com`
+
+Note: According to S3 specification, the URL used to sign must not contain path or query parameters. So make sure your `CDN_URL` variable does not contain path or query parameters.
+Example of **incorrect** value: `http://yourdomain.com/files/` (contains path)
+Example of **correct** value: `http://cdn.yourdomain.com` (no path or query parameters)
+
+## Additional Resources
+
+- [Official Alexandrie GitHub Repository](https://github.com/Smaug6739/alexandrie)
+- [Discord Community](https://discord.gg/UPsEg6egPj)
+
+## HTTPS errors when using MinIO/RustFS with Alexandrie
+
+**Symptoms**
+
+- error like `http: server gave HTTP response to HTTPS client`
+
+**Cause**
+This is usually caused by a misconfiguration of the `MINIO_SECURE` environment variable.
+
+**Correct configuration examples**
+
+- If your RustFS S3 server is running with HTTP (not HTTPS), then set: `MINIO_SECURE=false`
+- If your RustFS S3 server is running with HTTPS, then set: `MINIO_SECURE=true`
diff --git a/docs/README.md b/docs/README.md
index 3791202e..91203b20 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -196,7 +196,8 @@ 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*
+
+_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:
@@ -207,78 +208,52 @@ OIDC_1_CLIENT_SECRET: ${OIDC_1_CLIENT_SECRET}
OIDC_1_PROVIDER_NAME: ${OIDC_1_PROVIDER_NAME}
```
-## FAQ β€” Common Issues & Troubleshooting
-
-### I am instantly logged out after logging in (login loop)
-
-**Symptoms**
-
-- Login succeeds (no error message).
-- You are redirected correctly.
-- You are immediately logged out or returned to the login page.
-- Refreshing the page shows you as unauthenticated.
-
-**Cause**
-
-This is usually caused by a misconfiguration of the `COOKIE_DOMAIN` environment variable in the backend service.
-
-**Common mistakes**
-
-- Including protocol (http:// or https://) in `COOKIE_DOMAIN`.
-- Setting `COOKIE_DOMAIN` to a subdomain that does not match both frontend and backend domains.
-- Setting `COOKIE_DOMAIN` to a domain that does not match the actual domain used to access the services.
-
-**Correct configuration examples**
+### S3 / Minio β€” TLS, HTTPS and Custom Certificate Authorities
-- If your frontend is at `frontend.yourdomain.com` and your backend API is at `api.yourdomain.com`, then set `COOKIE_DOMAIN=yourdomain.com`.
-- If your frontend is at `frontend.subdomain.yourdomain.com` and your backend API is at `api.subdomain.yourdomain.com`, then set `COOKIE_DOMAIN=subdomain.yourdomain.com`.
-- If your frontend is at `yourdomain.com` and your backend API is at `api.yourdomain.com`, then set `COOKIE_DOMAIN=yourdomain.com`.
+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.
-### Files are uploaded but cannot be accessed
+This section explains how TLS is handled and how to configure it correctly.
-**Symptoms**
+#### HTTPS vs HTTP (MINIO_SECURE)
-- File uploads succeed without errors.
-- You show files as uploaded in the frontend (for example on the cdn page, in the datatable or in cards)
-- When trying to access the files, you get 404 errors or broken links.
-
-**Cause**
-This is usually caused by a misconfiguration of the `CDN_URL` and/or `CDN_ENDPOINT` environment variables in the backend service.
-
-**Common mistakes**
+```env
+MINIO_SECURE=true|false
+```
-- `CDN_URL` not matching the actual URL used to access to your S3 server storage (for example when using a reverse proxy with a different domain or path)
-- `CDN_ENDPOINT` not matching the bucket name or the path used in the reverse proxy.
+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.
-**Correct configuration examples**
+- `true` β†’ HTTPS is used (default)
+- `false` β†’ HTTP is used (no TLS)
-- If your RustFS S3 server is accessible at `http://cdn.yourdomain.com`, then set:
- - `CDN_URL=http://cdn.yourdomain.com`
- - `CDN_ENDPOINT=/alexandrie/` (/alexandrie/ is the default bucket name, change it only if you changed the bucket name or if your reverse proxy uses a different path)
-- If your RustFS S3 server is accessible at `http://yourdomain.com/files/`, then set:
- - `CDN_URL=http://yourdomain.com`
- - `CDN_ENDPOINT=/files/` (change /files/ to match the path used in your reverse proxy or the bucket name)
+#### Custom Certificate Authorities (MINIO_CA_PATH)
-Test the right url in your browser by combining `CDN_URL`, `CDN_ENDPOINT` and the object path (you can get the object path from the frontend interface, for example in the cdn page with devtools or by copying the link).
+If your S3 endpoint uses a certificate signed by an internal or private certificate authority, you must explicitly provide this CA to the backend.
-## I have errors with backup system or minio client
+```env
+MINIO_CA_PATH=/path/to/ca-certificate.pem
+```
-**Symptoms**
+- 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
-- Backup creation fails with errors related to link generation with S3 or MinIO (example: Failed to generate download URL: XML syntax error on line 1: attribute name without = in element)
+_Note: if you are using docker containers, you must mount this file into the backend container using a volume in `docker-compose.yml`._
-**Cause**
-This is usually caused if you have an incorrect value for endpoint of public signer with minio client in the backend service.
+_TLS Verification Bypass (Not Recommended)_
-**Correct configuration examples**
+```env
+MINIO_INSECURE_TLS=true|false
+```
-- If your RustFS S3 server is accessible at `http://cdn.yourdomain.com`, then set: `CDN_URL=http://cdn.yourdomain.com`
+This option disables TLS certificate verification while still using HTTPS.
-Note: According to S3 specification, the URL used to sign must not contain path or query parameters. So make sure your `CDN_URL` variable does not contain path or query parameters.
-Example of **incorrect** value: `http://yourdomain.com/files/` (contains path)
-Example of **correct** value: `http://cdn.yourdomain.com` (no path or query parameters)
+- The connection remains encrypted
+- Certificate validation (CA + hostname) is skipped
-## Additional Resources
+⚠️ Security warning
+This option should only be used for:
-- [Official Alexandrie GitHub Repository](https://github.com/Smaug6739/alexandrie)
-- [Discord Community](https://discord.gg/UPsEg6egPj)
+- temporary debugging
+- local testing environments
+- It is not recommended for production use.
diff --git a/docs/env.md b/docs/env.md
new file mode 100644
index 00000000..090d3bd5
--- /dev/null
+++ b/docs/env.md
@@ -0,0 +1,120 @@
+# Alexandrie β€” Environment Variables Reference
+
+This document provides a **concise reference of all supported environment variables** in Alexandrie.
+
+Only variables documented here and in `.env.example` are officially supported.
+
+---
+
+## Public URLs & Global Access
+
+| Variable | Accepted Values | Description |
+| -------------- | -------------------------- | --------------------------------------------------------------------------------------- |
+| `FRONTEND_URL` | URL | Public URL of the frontend application (used by clients/browsers). |
+| `API_URL` | URL | Public URL of the backend API. |
+| `CDN_URL` | URL (no path/query) | Public base URL of the S3-compatible storage (RustFS / CDN). |
+| `CDN_ENDPOINT` | Path (e.g. `/alexandrie/`) | Path prefix used to expose objects. Combined as `<CDN_URL><CDN_ENDPOINT><object-path>`. |
+
+---
+
+## Application Feature Flags
+
+| Variable | Accepted Values | Default | Description |
+| ------------------------ | ---------------- | ------- | ------------------------------------------------------- |
+| `CONFIG_DISABLE_LANDING` | `true` / `false` | `false` | Disables the landing page and redirects users to login. |
+| `CONFIG_DISABLE_SIGNUP` | `true` / `false` | `false` | Disables new user registrations (frontend + backend). |
+
+---
+
+## Backend API β€” Runtime & Security
+
+| Variable | Accepted Values | Description |
+| ----------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `BACKEND_EXTERNAL_PORT` | Port number | Port exposed on the host for the backend API. |
+| `COOKIE_DOMAIN` | Domain (no protocol) | Domain scope for authentication cookies. Must match the highest common domain between frontend and backend. |
+| `ALLOW_UNSECURE` | `true` / `false` | Allows HTTP connections (recommended `false` in production). |
+| `JWT_SECRET` | String | Secret key used to sign JWT tokens. Changing it invalidates all sessions. |
+
+---
+
+## Database β€” MySQL
+
+| Variable | Accepted Values | Description |
+| --------------------- | --------------- | ----------------------------------- |
+| `MYSQL_EXTERNAL_PORT` | Port number | Port exposed on the host for MySQL. |
+| `MYSQL_DATABASE` | String | Name of the default database. |
+| `MYSQL_USER` | String | Database user for Alexandrie. |
+| `MYSQL_PASSWORD` | String | Password for the database user. |
+| `MYSQL_ROOT_PASSWORD` | String | MySQL root password. |
+
+---
+
+## Object Storage β€” RustFS / S3
+
+### RustFS Service Configuration
+
+| Variable | Accepted Values | Description |
+| ---------------------- | --------------- | ---------------------------------------------------------------------------------- |
+| `RUSTFS_EXTERNAL_PORT` | Port number | Port exposed on the host for RustFS. |
+| `RUSTFS_ACCESS_KEY` | String | Access key for the S3-compatible API. |
+| `RUSTFS_SECRET_KEY` | String | Secret key for the S3-compatible API. |
+| `MINIO_BUCKET` | String | Main bucket name. Backend automatically creates `<bucket>` and `<bucket>-backups`. |
+
+---
+
+### S3 / MinIO β€” TLS & HTTPS
+
+| Variable | Accepted Values | Default | Description |
+| -------------------- | ---------------- | ------- | -------------------------------------------------------------------------------------------------------------- |
+| `MINIO_SECURE` | `true` / `false` | `true` | Enables HTTPS (TLS) when connecting to the S3 endpoint. Must match how the server is exposed. |
+| `MINIO_CA_PATH` | File path | β€” | Path to a custom CA certificate (PEM) for internal or private PKI. Must be mounted into the backend container. |
+| `MINIO_INSECURE_TLS` | `true` / `false` | `false` | Disables TLS certificate verification while keeping HTTPS enabled (not recommended for production). |
+
+---
+
+## Email β€” SMTP (optional)
+
+| Variable | Accepted Values | Description |
+| --------------- | --------------- | ------------------------------ |
+| `SMTP_HOST` | Hostname | SMTP server host. |
+| `SMTP_MAIL` | Email address | Sender email address. |
+| `SMTP_PASSWORD` | String | Password for the SMTP account. |
+
+---
+
+## Frontend β€” Nuxt
+
+| Variable | Accepted Values | Description |
+| ------------------------ | --------------- | ---------------------------------------------------- |
+| `FRONTEND_EXTERNAL_PORT` | Port number | Port exposed on the host for the frontend container. |
+
+---
+
+## Advanced Backend Configuration
+
+| Variable | Accepted Values | Description |
+| ------------- | --------------- | ---------------------------------------------------------------- |
+| `CONFIG_PATH` | File path | Path to a custom `config.toml` file overriding backend defaults. |
+
+---
+
+## OIDC Integration
+
+Up to **10 OpenID Connect providers** can be configured.
+
+| Variable | Accepted Values | Description |
+| ------------------------ | --------------- | ------------------------------------------------------------------- |
+| `OIDC_{i}_CONFIG_URL` | URL | OpenID configuration endpoint (`.well-known/openid-configuration`). |
+| `OIDC_{i}_CLIENT_ID` | String | Client ID issued by the provider. |
+| `OIDC_{i}_CLIENT_SECRET` | String | Client secret issued by the provider. |
+| `OIDC_{i}_PROVIDER_NAME` | String | Display name of the provider (e.g. Google, GitHub, Microsoft). |
+
+Replace `{i}` with a number between **1 and 10**.
+
+---
+
+## Notes
+
+- Variables related to TLS trust **must be configured inside the backend container**, not only on the host.
+- `MINIO_INSECURE_TLS` should only be used for temporary debugging.
+- `MINIO_SECURE=false` is required for local RustFS deployments without TLS (e.g. `localhost`).