π The open-source, offline-first Notion, Obsidian & Confluence alternative. Advanced Markdown, multi-tenant teams, OIDC/SSO, and local S3 backups. Deploy in one command.
Vue dockergolangkanbanknowledge-baseknowledge-managementmarkdownnote-takingnotesnotes-appnotionnuxtnuxtjsoffline-firstoidcpwaselfhostedssovuevuejswiki
docs: documentation for MINIO_CA_PATH and MINIO_INSECURE_TLS variables
Smaug6739a7ade8087fcc
diff --git a/docs/FAQ.md b/docs/FAQ.mdnew file mode 100644index 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.mdindex 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.mdnew file mode 100644index 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`).