cjw/Oxicloud
1
0
Fork 0
Code Issues Pull Requests Actions 4 Packages Projects Releases Wiki Activity

docs: migrate legacy docs to official site

Browse Source
This commit is contained in:
Diocrafts
2026-04-22 07:50:41 +02:00
parent e10a908f07
commit c0cb86c273
63 changed files with 1646 additions and 10136 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/config/admin-settings.md
+86
View File
@@ -0,0 +1,86 @@
# Admin Settings
OxiCloud exposes an admin API for runtime configuration, dashboard stats, and user administration. All routes live under `/api/admin` and require an authenticated admin JWT.
## Settings Endpoints
| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/api/admin/settings/oidc` | Read current OIDC settings |
| `PUT` | `/api/admin/settings/oidc` | Save OIDC settings |
| `POST` | `/api/admin/settings/oidc/test` | Test provider connectivity |
| `GET` | `/api/admin/settings/general` | Read general server settings |
The OIDC runtime UI complements the base configuration described in [OIDC / SSO](/config/oidc) and the provider samples in [OIDC Config Examples](/config/oidc-config-examples).
## Dashboard Endpoint
| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/api/admin/dashboard` | Read server statistics and feature state |
Typical dashboard fields include:
- server version
- whether auth and OIDC are enabled
- whether quotas are enabled
- total, active, and admin user counts
- quota usage totals and percentage
## User Management Endpoints
| Method | Path | Description |
| --- | --- | --- |
| `GET` | `/api/admin/users` | List users |
| `GET` | `/api/admin/users/{id}` | Get one user |
| `DELETE` | `/api/admin/users/{id}` | Delete a user |
| `PUT` | `/api/admin/users/{id}/role` | Change role |
| `PUT` | `/api/admin/users/{id}/active` | Activate or deactivate a user |
| `PUT` | `/api/admin/users/{id}/quota` | Update a storage quota |
### Built-in safety guards
- Admins cannot delete their own account
- Admins cannot change their own role
- Admins cannot deactivate themselves
## OIDC Settings Priority
When the same setting exists in multiple places, OxiCloud resolves it in this order:
1. Environment variables such as `OXICLOUD_OIDC_*`
2. Values stored in the admin settings table
3. Built-in defaults
If a value is overridden by environment variables, the admin API can expose that in the response so operators know why a saved value is not taking effect.
## Test Connection Example
```json
{
"issuer_url": "https://keycloak.example.com/realms/main"
}
```
Successful responses include discovered endpoints such as the authorization endpoint, token endpoint, and userinfo endpoint.
## Data Storage
Runtime settings are stored in `auth.admin_settings`.
```sql
CREATE TABLE IF NOT EXISTS auth.admin_settings (
key TEXT PRIMARY KEY,
value TEXT NOT NULL,
category TEXT NOT NULL,
is_secret BOOLEAN DEFAULT FALSE,
updated_by VARCHAR(36),
updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);
```
## Related Pages
- [OIDC / SSO](/config/oidc)
- [OIDC Config Examples](/config/oidc-config-examples)
- [Environment Variables](/config/env)
docs/config/authentication.md
+72
View File
@@ -0,0 +1,72 @@
# Authentication
OxiCloud ships with JWT-based authentication and Argon2id password hashing for local accounts. It also exposes status and OIDC-related auth endpoints under the same `/api/auth` namespace.
## Core Endpoints
| Method | Endpoint | Description |
| --- | --- | --- |
| `POST` | `/api/auth/register` | Create a local user account |
| `POST` | `/api/auth/login` | Exchange username and password for access and refresh tokens |
| `POST` | `/api/auth/refresh` | Refresh the session tokens |
| `GET` | `/api/auth/me` | Return the current authenticated user |
| `PUT` | `/api/auth/change-password` | Change the current user's password |
| `POST` | `/api/auth/logout` | Invalidate the current session |
| `GET` | `/api/auth/status` | Return auth system state, including OIDC availability |
## OIDC Endpoints Under Auth
| Method | Endpoint | Description |
| --- | --- | --- |
| `GET` | `/api/auth/oidc/providers` | List configured OIDC provider info |
| `GET` | `/api/auth/oidc/authorize` | Build the authorization redirect URL |
| `GET` | `/api/auth/oidc/callback` | Handle provider redirect callback |
| `POST` | `/api/auth/oidc/exchange` | Exchange the auth code for OxiCloud session tokens |
## Example Flows
### Register
```json
{
"username": "testuser",
"email": "test@example.com",
"password": "SecurePassword123"
}
```
### Login
```json
{
"username": "testuser",
"password": "SecurePassword123"
}
```
Typical successful login response:
```json
{
"accessToken": "...",
"refreshToken": "...",
"expiresIn": 3600
}
```
### Current User
`GET /api/auth/me` returns the authenticated user's identity, role, and storage information.
## Security Model
- local passwords are hashed with Argon2id
- access control is role-based (`admin` and `user`)
- refresh tokens support session renewal without forcing frequent re-login
- OIDC can coexist with local auth or disable password login entirely
## Related Pages
- [OIDC / SSO](/config/oidc)
- [Admin Settings](/config/admin-settings)
- [Environment Variables](/config/env)
docs/config/deployment.md
+21 -5
View File
@@ -16,14 +16,18 @@ The final image runs as non-root user `oxicloud` (UID/GID 1001). Exposed port: *
```yaml
services:
postgres:
image: postgres:17.4-alpine
image: postgres:18.2-alpine3.23
restart: always
environment:
POSTGRES_DB: oxicloud
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres # change in production!
POSTGRES_PASSWORD: postgres
ports:
- "5432:5432"
networks:
- oxicloud
volumes:
- pg_data:/var/lib/postgresql/data
- ./db/schema.sql:/docker-entrypoint-initdb.d/schema.sql
- pg_data:/var/lib/postgresql/
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
@@ -31,9 +35,15 @@ services:
retries: 5
oxicloud:
image: ghcr.io/diocrafts/oxicloud:latest
image: diocrafts/oxicloud:latest
restart: always
build:
context: .
dockerfile: Dockerfile
ports:
- "8086:8086"
networks:
- oxicloud
env_file:
- .env
volumes:
@@ -42,11 +52,17 @@ services:
postgres:
condition: service_healthy
networks:
oxicloud:
driver: bridge
volumes:
pg_data:
storage_data:
```
This example mirrors the repository's current `docker-compose.yml`. If you deploy from a registry-only setup, you can keep the `image:` line and remove the `build:` stanza.
## Kubernetes (Helm)
### Prerequisites
docs/config/env.md
+18 -1
View File
@@ -1,6 +1,6 @@
# Environment Variables
All variables use the `OXICLOUD_` prefix.
Most runtime variables use the `OXICLOUD_` prefix. A few build-time or allocator variables do not.
## Server
@@ -19,6 +19,14 @@ All variables use the `OXICLOUD_` prefix.
| `OXICLOUD_DB_CONNECTION_STRING` | `postgres://postgres:postgres@localhost:5432/oxicloud` | PostgreSQL connection string |
| `OXICLOUD_DB_MAX_CONNECTIONS` | `20` | Max pool connections |
| `OXICLOUD_DB_MIN_CONNECTIONS` | `5` | Min pool connections |
| `OXICLOUD_DB_MAINTENANCE_MAX_CONNECTIONS` | `5` | Max connections in the isolated maintenance pool |
| `OXICLOUD_DB_MAINTENANCE_MIN_CONNECTIONS` | `1` | Min connections in the isolated maintenance pool |
## Build-Time SQLx
| Variable | Default | Description |
|---|---|---|
| `DATABASE_URL` | — | Build-time database URL for SQLx compile-time checks |
## Authentication
@@ -68,6 +76,15 @@ See the [WOPI configuration guide](/config/wopi) for details.
| `OXICLOUD_WOPI_TOKEN_TTL_SECS` | `86400` | Token lifetime |
| `OXICLOUD_WOPI_LOCK_TTL_SECS` | `1800` | Lock expiration |
## Allocator Tuning
These variables are read directly by **mimalloc**, not by OxiCloud's config parser.
| Variable | Default | Description |
|---|---|---|
| `MIMALLOC_PURGE_DELAY` | `0` | Delay in ms before freed memory is returned to the OS |
| `MIMALLOC_ALLOW_LARGE_OS_PAGES` | `0` | Enable or disable large OS pages for allocations |
## Internal Defaults (not configurable via env)
| Parameter | Default |
docs/config/index.md
+1
View File
@@ -6,6 +6,7 @@ OxiCloud is configured entirely via **environment variables** (no config files n
- [Deployment & Docker](/config/deployment) — Docker Compose, Kubernetes Helm chart, image details
- [Environment Variables](/config/env) — complete reference of all `OXICLOUD_*` variables
- [Authentication](/config/authentication) — JWT auth, login, refresh, password changes, and auth status
- [OIDC / SSO](/config/oidc) — single sign-on with Keycloak, Authentik, Authelia, Google, Azure AD
- [WOPI (Office Editing)](/config/wopi) — Collabora Online / OnlyOffice integration
docs/config/oidc-config-examples.md
+107
View File
@@ -0,0 +1,107 @@
# OIDC Config Examples
This page collects provider-specific OpenID Connect examples for OxiCloud. Use it together with the base reference in [OIDC / SSO](/config/oidc).
## Base Environment Variables
```bash
OXICLOUD_OIDC_ENABLED=true
OXICLOUD_OIDC_PROVIDER_NAME="Display Name"
OXICLOUD_OIDC_ISSUER_URL="https://provider.example.com/realms/your-realm"
OXICLOUD_OIDC_CLIENT_ID="your-client-id"
OXICLOUD_OIDC_CLIENT_SECRET="your-client-secret"
OXICLOUD_OIDC_REDIRECT_URI="https://your-oxicloud.example.com/api/auth/oidc/callback"
OXICLOUD_OIDC_SCOPES="openid profile email"
OXICLOUD_OIDC_FRONTEND_URL="https://your-oxicloud.example.com"
OXICLOUD_OIDC_AUTO_PROVISION="true"
OXICLOUD_OIDC_ADMIN_GROUPS="admin-group"
OXICLOUD_OIDC_DISABLE_PASSWORD_LOGIN="false"
```
## Authentik
1. Create an OAuth2 or OpenID Connect application for OxiCloud
2. Register `https://your-oxicloud.example.com/api/auth/oidc/callback` as the callback URL
3. Copy the generated client ID and client secret
```yaml
services:
oxicloud:
image: diocrafts/oxicloud:latest
environment:
OXICLOUD_OIDC_ENABLED: "true"
OXICLOUD_OIDC_PROVIDER_NAME: "Authentik"
OXICLOUD_OIDC_ISSUER_URL: "https://authentik.example.com/application/o/oxicloud"
OXICLOUD_OIDC_CLIENT_ID: "your-authentik-client-id"
OXICLOUD_OIDC_CLIENT_SECRET: "your-authentik-client-secret"
OXICLOUD_OIDC_REDIRECT_URI: "https://oxicloud.example.com/api/auth/oidc/callback"
OXICLOUD_OIDC_SCOPES: "openid profile email"
OXICLOUD_OIDC_FRONTEND_URL: "https://oxicloud.example.com"
```
## Authelia
Configure an OIDC client in Authelia and allow OxiCloud's redirect URI.
```yaml
identity_providers:
oidc:
clients:
- id: oxicloud
description: OxiCloud
public: false
redirect_uris:
- https://oxicloud.example.com/api/auth/oidc/callback
scopes: [openid, profile, email, groups]
```
```yaml
services:
oxicloud:
image: diocrafts/oxicloud:latest
environment:
OXICLOUD_OIDC_PROVIDER_NAME: "Authelia"
OXICLOUD_OIDC_ISSUER_URL: "https://authelia.example.com"
OXICLOUD_OIDC_CLIENT_ID: "oxicloud"
OXICLOUD_OIDC_CLIENT_SECRET: "your-client-secret"
```
## Keycloak
1. Create a confidential client named `oxicloud`
2. Set the valid redirect URI to `https://oxicloud.example.com/api/auth/oidc/callback`
3. Copy the generated client secret
```yaml
services:
oxicloud:
image: diocrafts/oxicloud:latest
environment:
OXICLOUD_OIDC_PROVIDER_NAME: "Keycloak"
OXICLOUD_OIDC_ISSUER_URL: "https://keycloak.example.com/realms/your-realm"
OXICLOUD_OIDC_CLIENT_ID: "oxicloud"
OXICLOUD_OIDC_CLIENT_SECRET: "your-keycloak-client-secret"
OXICLOUD_OIDC_ADMIN_GROUPS: "oxicloud-admins"
```
## Troubleshooting
### Failed to discover the provider
- Verify the issuer URL exactly matches the provider's discovery URL base
- Check DNS, TLS, and network reachability from the OxiCloud container or host
### Invalid redirect URI
- Make the configured callback match exactly on scheme, host, port, and path
- Check for `http` versus `https` mismatches
### Auto-provisioning problems
- Enable `OXICLOUD_OIDC_AUTO_PROVISION=true` if first-login account creation is expected
- Make sure `openid` is included in the configured scopes
## Related Pages
- [OIDC / SSO](/config/oidc)
- [Admin Settings](/config/admin-settings)
docs/config/oidc.md
+19
View File
@@ -10,6 +10,16 @@ OxiCloud supports OpenID Connect for single sign-on with providers like **Keyclo
4. IdP redirects back to OxiCloud with an auth code
5. OxiCloud exchanges the code for user info and issues its own JWT tokens
## Architecture
OIDC follows the Authorization Code Flow and keeps a clear split between provider communication and local session handling.
- `OidcService` discovers provider metadata, builds authorization URLs, exchanges authorization codes, and validates the token response
- `AuthApplicationService` coordinates user lookup or auto-provisioning and then issues OxiCloud's own access and refresh tokens
- the auth handler exposes the public OIDC endpoints under `/api/auth/oidc/*`
After the browser returns from the IdP, OxiCloud does not reuse the provider token for app requests. It converts the identity into its own JWT session model.
## Configuration
```bash
@@ -54,6 +64,15 @@ If `OXICLOUD_OIDC_ENABLED=true` but `issuer_url`, `client_id`, or `client_secret
| GET | `/api/auth/oidc/callback` | Callback from IdP with auth code |
| POST | `/api/auth/oidc/exchange` | Exchange auth code for JWT tokens |
## Identity Mapping
OIDC users are matched by the pair:
- `oidc_provider`
- `oidc_subject`
This allows one external identity to map to one local user record and supports just-in-time provisioning when `OXICLOUD_OIDC_AUTO_PROVISION=true`.
## Provider Examples
### Keycloak
docs/config/wopi.md
+28 -1
View File
@@ -9,6 +9,15 @@ OxiCloud integrates with **Collabora Online** and **OnlyOffice** via the WOPI pr
3. The editor fetches the file from OxiCloud via WOPI endpoints
4. Edits are saved back via `PutFile`
## Host / Client Flow
OxiCloud acts as the **WOPI host** and Collabora or OnlyOffice acts as the **WOPI client**.
1. OxiCloud loads the discovery document from the configured WOPI client
2. The frontend opens a host page that embeds the editor in an iframe
3. The iframe URL includes `WOPISrc`, which points back to OxiCloud's `/wopi/files/*` endpoints
4. The editor calls back into OxiCloud with the WOPI access token to read, lock, and save the file
## Configuration
```bash
@@ -68,7 +77,25 @@ services:
| GET | `/wopi/files/{id}` | CheckFileInfo — file metadata |
| GET | `/wopi/files/{id}/contents` | GetFile — download file content |
| POST | `/wopi/files/{id}/contents` | PutFile — save edited content |
| POST | `/wopi/files/{id}` | Lock / Unlock / RefreshLock |
| POST | `/wopi/files/{id}` | Lock / Unlock / RefreshLock / Rename / Delete / Save As |
### Common `X-WOPI-Override` operations
| Override | Purpose |
| --- | --- |
| `LOCK` | Acquire or refresh an editor lock |
| `UNLOCK` | Release a lock |
| `REFRESH_LOCK` | Extend the current lock |
| `PUT_RELATIVE` | Save as a related file |
| `RENAME_FILE` | Rename from inside the editor |
| `DELETE` | Delete from the editor when supported |
## Notes
- `CheckFileInfo` is required for every WOPI action
- `PutFile` uploads the full file content back to OxiCloud
- lock conflicts return `409 Conflict` with the current lock value
- OxiCloud uses query parameter `?access_token=` authentication for WOPI callbacks instead of the standard JWT middleware
## Supported Formats