From 63f5bc91a935ada5edc230fa1c9a67771b5622cd Mon Sep 17 00:00:00 2001 From: Heiko Pohl Date: Wed, 11 Mar 2026 10:33:09 +0100 Subject: [PATCH 1/4] refining docker compose documentaions in rolling --- .../docker-compose/docker-compose-base.md | 208 ++---------------- .../container/docker-compose/keycloak.md | 2 +- .../production-setup-consideration.md | 68 ++++++ .../verify-SSL-certification.md | 101 +++++++++ 4 files changed, 188 insertions(+), 191 deletions(-) create mode 100644 docs/admin/getting-started/container/docker-compose/production-setup-consideration.md create mode 100644 docs/admin/getting-started/container/docker-compose/verify-SSL-certification.md diff --git a/docs/admin/getting-started/container/docker-compose/docker-compose-base.md b/docs/admin/getting-started/container/docker-compose/docker-compose-base.md index d1354e5f..4daa5a2e 100644 --- a/docs/admin/getting-started/container/docker-compose/docker-compose-base.md +++ b/docs/admin/getting-started/container/docker-compose/docker-compose-base.md @@ -8,9 +8,9 @@ draft: false # OpenCloud with Docker Compose -Install an internet-facing OpenCloud with SSL certification using Docker Compose. +Install an internet-facing OpenCloud instance with SSL certificates using Docker Compose. -This installation documentation is for Ubuntu and Debian systems. The software can also be installed on other Linux distributions, but the commands and package managers may differ. +This installation guide is written for Ubuntu and Debian systems. The software can also be installed on other Linux distributions, but commands and package managers may differ. ## Prerequisites @@ -29,13 +29,9 @@ This installation documentation is for Ubuntu and Debian systems. The software c Log into your server via SSH: ```bash -ssh YOUR_ADMIN_USER@YOUR.SERVER.IP +ssh root@YOUR.SERVER.IP ``` -:::note -Use a non-root user with `sudo` privileges. If you logged in as root, prepend `sudo` where appropriate or run the commands without `sudo` -::: - ## Install Docker Update your system and install Docker. @@ -43,7 +39,7 @@ Update your system and install Docker. First, perform an update and upgrade: ```bash -sudo apt update && sudo apt upgrade -y +apt update && apt upgrade -y ``` Install Docker following the [official Docker guide](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository) @@ -51,22 +47,9 @@ Install Docker following the [official Docker guide](https://docs.docker.com/eng Once Docker is installed, enable and start the service: ```bash -sudo systemctl enable docker && sudo systemctl start docker +systemctl enable docker && systemctl start docker ``` -## Create a dedicated user to run OpenCloud (recommended) - -For security reasons, do not run the OpenCloud stack as `root`. Create a dedicated user (for example `opencloud`) and run the remaining steps as that user. - -```bash -sudo adduser opencloud -sudo usermod -aG docker opencloud -``` - -Log out and log back in (or start a new login shell), then continue as `opencloud`. - -Docker can be managed as a non-root user (e.g. via the `docker` group). Be aware that access to the Docker daemon is effectively equivalent to root access on the host. Limit group membership and restrict access accordingly. - ## Clone the OpenCloud Repository Download the necessary configuration files: @@ -77,7 +60,7 @@ git clone https://github.com/opencloud-eu/opencloud-compose.git ## Configure the .env File for Staging Certificates -Before requesting real SSL certificates, test the setup with Let's Encrypt’s staging environment. +Before requesting real SSL certificates, it is recommended to test the setup using Let's Encrypt’s staging environment. ### Navigate to the OpenCloud configuration folder @@ -95,25 +78,25 @@ cp .env.example .env The repository includes .env.example as a template with default settings and documentation. Your actual .env file is excluded from version control (via .gitignore) to prevent accidentally committing sensitive information like passwords and domain-specific settings. ::: -Edit the `.env` file with the editor of your choice: +## Modify these settings + +### Edit the `.env` file with the editor of your choice -### In our example we use nano +In our example we use nano ```bash nano .env ``` -## Modify these settings - ### Disable insecure mode -```env +```bash # INSECURE=true ``` ### Set your domain names -```env +```bash TRAEFIK_DOMAIN=traefik.YOUR.DOMAIN OC_DOMAIN=cloud.YOUR.DOMAIN COLLABORA_DOMAIN=collabora.YOUR.DOMAIN @@ -122,106 +105,31 @@ WOPISERVER_DOMAIN=wopiserver.YOUR.DOMAIN ### Set your admin password -```env +```bash INITIAL_ADMIN_PASSWORD=YourSecurePassword ``` ### Set your email for SSL certification -```env +```bash TRAEFIK_ACME_MAIL=your@email.com ``` ### Use Let's Encrypt staging certificates (for testing) -```env +```bash TRAEFIK_ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory ``` ### Set your deployment options -For example, without Collabora: - -```env -COMPOSE_FILE=docker-compose.yml:traefik/opencloud.yml -``` - -Save and exit. - -### Production Setup Consideration - -:::caution Production Setup Recommended -By default, OpenCloud stores configuration and data inside internal Docker volumes. -This works fine for local development or quick evaluations — but is not suitable for production environments. -::: - -#### Mount Persistent Volumes - -For production setups, mount persistent host directories for configuration and data. This gives you: - -- Data durability -- Easier backups and recovery -- Full control over storage location and permissions - -Update your `.env` file with custom paths: - -```env -OC_CONFIG_DIR=/your/local/path/opencloud/config -OC_DATA_DIR=/your/local/path/opencloud/data -``` - -### UID/GID and volume permissions (important) - -OpenCloud containers run as `1000:1000` by default. -If your host user uses different IDs, set `OC_CONTAINER_UID_GID` in `.env` so file ownership matches your host user: - -```env -OC_CONTAINER_UID_GID=1001:1001 -``` - -You can check your UID/GID with: - -```bash -id -u -id -g -``` - -:::tip Folder Permissions - -Create the folders and assign ownership to the UID/GID used by the container (default `1000:1000`, or your `OC_CONTAINER_UID_GID` value): +Example configuration without Collabora: ```bash -sudo mkdir -p /your/local/path/opencloud/{config,data} -sudo chown -R $(id -u):$(id -g) /your/local/path/opencloud -``` - -::: - -If `OC_CONFIG_DIR` and `OC_DATA_DIR` are not set, Docker uses internal volumes. Those are harder to manage for backups and are not recommended for production. - -:::caution Security Warning - -Any local account that matches the mapped UID/GID can access these mounted directories. -In shared or multi-user environments, this can expose OpenCloud config and data files. - -Use strict host-level permission management and isolate access to these paths where possible. - -::: - -#### Use production release container - -To avoid accidentally updating to a version with breaking changes, you should specify the production container version to be used in your `.env` file: - -```env -OC_DOCKER_IMAGE=opencloudeu/opencloud -OC_DOCKER_TAG=4.0.3 +COMPOSE_FILE=docker-compose.yml:traefik/opencloud.yml ``` -:::tip Keep the version up to date -The documentation may not always reference the latest available release. Before deploying (and when updating), check the available tags on Docker Hub and adjust `OC_DOCKER_TAG` to the most recent stable version: - -[Docker Hub – opencloudeu/opencloud tags](https://hub.docker.com/r/opencloudeu/opencloud/tags) -::: +Save the file and exit the editor. ## Start OpenCloud @@ -232,83 +140,3 @@ docker compose up -d ``` This will start all required services in the background. - -## Verify SSL Certification - -In your web browser, visit: - -```bash -https://cloud.YOUR.DOMAIN -``` - -You should see a security warning because the staging certificate is not fully trusted. -The same warning should appear for the other domains you are using. - -Example with Chrome browser: - -Certificate Details - -- Check the certificate details to confirm it’s from Let's Encrypt Staging. - - Certificate Details - Certificate Details - -## Apply a Real SSL Certificate - -Once the staging certificate works, switch to a production certificate. - -### Stop Docker Compose - -```bash -docker compose down -``` - -### Remove old staging certificates - -```bash -rm -rf ./certs -``` - -(Run this in the `opencloud-compose` directory. If you changed volume names, adjust accordingly.) - -### Disable staging mode in `.env` - -```bash -nano .env -``` - -Comment the staging server: - -```env -# TRAEFIK_ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory -``` - -### Restart OpenCloud with a real SSL certificate - -```bash -docker compose up -d -``` - -Now, visiting `https://cloud.YOUR.DOMAIN` should show a secure connection with a valid SSL certificate. - -Certificate Details - -## Log into OpenCloud - -Open a browser and visit: - -```bash -https://cloud.YOUR.DOMAIN -``` - -Login with: - -Username: `admin` - -Password: (your password) - -Admin general - -## Troubleshooting - -If you encounter any issues, check the [Common Issues & Help](../../../resources/common-issues) diff --git a/docs/admin/getting-started/container/docker-compose/keycloak.md b/docs/admin/getting-started/container/docker-compose/keycloak.md index f6762b0b..03e40ec4 100644 --- a/docs/admin/getting-started/container/docker-compose/keycloak.md +++ b/docs/admin/getting-started/container/docker-compose/keycloak.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 id: keycloak title: Keycloak description: 'OpenCloud with Keycloak.' diff --git a/docs/admin/getting-started/container/docker-compose/production-setup-consideration.md b/docs/admin/getting-started/container/docker-compose/production-setup-consideration.md new file mode 100644 index 00000000..98486e2c --- /dev/null +++ b/docs/admin/getting-started/container/docker-compose/production-setup-consideration.md @@ -0,0 +1,68 @@ +--- +sidebar_position: 3 +id: production-setup-consideration +title: Production Setup Consideration +description: 'OpenCloud Production Setup Consideration' +draft: true +--- + +# Production Setup Consideration + +:::caution Production Setup Recommended +By default, OpenCloud stores configuration and data inside internal Docker volumes. +This works fine for local development or quick evaluations — but is not suitable for production environments. +::: + +## Mount Persistent Volumes + +For production deployments, you should mount persistent local directories for configuration and data. This ensures: + +- Data durability +- Easier backups and recovery +- Full control over storage location and permissions + +### Update your `.env` file with custom paths + +```bash +OC_CONFIG_DIR=/your/local/path/opencloud/config +OC_DATA_DIR=/your/local/path/opencloud/data +``` + +### Set your email for SSL certification + +```bash +TRAEFIK_ACME_MAIL=your@email.com +``` + +:::tip Folder Permissions + +### Ensure these folders exist and are owned by user and group 1000:1000, which the Docker containers use by default + +```bash +sudo mkdir -p /your/local/path/opencloud/{config,data} +sudo chown -R 1000:1000 /your/local/path/opencloud +``` + +::: + +If these variables are not set, Docker will use internal volumes. +These volumes may be removed when containers are deleted, which means your configuration and data may be lost. This setup is therefore not recommended for production use. + +:::caution Security Warning + +The user with UID 1000 on your host system will have full access to these mounted directories. This means that any local user account with this ID can read, modify, or delete OpenCloud config and data files. + +This can pose a security risk in shared or multi-user environments. Make sure to implement proper user and permission management and consider isolating access to these directories. + +::: + +## Use production release container + +To avoid accidentally upgrading to versions that may contain breaking changes, you should explicitly specify the container image and version in your .env file. + +```bash +OC_DOCKER_IMAGE=opencloudeu/opencloud +OC_DOCKER_TAG=2 +``` + +This ensures that your deployment always uses a stable production release instead of automatically pulling newer versions. diff --git a/docs/admin/getting-started/container/docker-compose/verify-SSL-certification.md b/docs/admin/getting-started/container/docker-compose/verify-SSL-certification.md new file mode 100644 index 00000000..7fa9acde --- /dev/null +++ b/docs/admin/getting-started/container/docker-compose/verify-SSL-certification.md @@ -0,0 +1,101 @@ +--- +sidebar_position: 4 +id: verify-SSL-certification +title: Verify SSL Certification +description: 'Verify SSL Certification in OpenCloud' +draft: true +--- + +# Verify SSL Certification + +## After starting OpenCloud, verify that the SSL certificates were issued correctly + +Open the following URL in your web browser: + +```bash +https://cloud.YOUR.DOMAIN +``` + +Because the setup currently uses Let's Encrypt staging certificates, your browser will show a security warning. This is expected, as staging certificates are not trusted by browsers. + +The same warning may appear for the other domains you configured. + +Example in the Chrome browser: + +Certificate Details + +- Check the certificate details to confirm that the certificate was issued by Let's Encrypt Staging. + + Certificate Details + Certificate Details + +## Apply a Real SSL Certificate + +Once the staging certificate works correctly, you can switch to a production SSL certificate. + +### Stop Docker Compose + +Stop the running containers: + +```bash +docker compose down +``` + +### Remove old staging certificates + +Delete the previously generated staging certificates: + +```bash +rm -r certs +``` + +If you changed volume names or paths, adjust this command accordingly. + +### Disable staging mode in `.env` + +Open the environment file: + +```bash +nano .env +``` + +Comment the staging server: + +```bash +# TRAEFIK_ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory +``` + +### Restart OpenCloud with a real SSL certificate + +Start the containers again: + +```bash +docker compose up -d +``` + +OpenCloud will now request trusted production certificates from Let's Encrypt. + +After a short moment, visiting the following URL should show a secure HTTPS connection: + +Certificate Details + +## Log into OpenCloud + +Open a browser and visit: + +```bash +https://cloud.YOUR.DOMAIN +``` + +Login with: + +Username: `admin` + +Password: (the password you configured in the .env file) + +Admin general + +## Troubleshooting + +If you encounter any issues during the setup process, check the troubleshooting guide: +[Common Issues & Help](../../../resources/common-issues) From bbee10e7dc5b966465d7dbd8ef08a992b2acb05d Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Thu, 12 Mar 2026 14:30:36 +0100 Subject: [PATCH 2/4] change structure and add new files and informations --- .../container/docker-compose/_category_.json | 5 +- .../docker-compose/docker-external-proxy.md | 18 +- .../container/docker-compose/index.md | 57 ++++ ...-compose-base.md => integrated-traefik.md} | 46 +++- .../docker-compose/keycloak-deployment.md | 151 +++++++++++ .../container/docker-compose/keycloak.md | 91 ------- .../production-considerations.md | 104 ++++++++ .../production-setup-consideration.md | 68 ----- .../verify-SSL-certification.md | 101 -------- .../docker-compose/verify-tls-certificates.md | 171 ++++++++++++ .../docker-compose/volume-permissions.md | 245 ++++++++++++++++++ 11 files changed, 782 insertions(+), 275 deletions(-) create mode 100644 docs/admin/getting-started/container/docker-compose/index.md rename docs/admin/getting-started/container/docker-compose/{docker-compose-base.md => integrated-traefik.md} (58%) create mode 100644 docs/admin/getting-started/container/docker-compose/keycloak-deployment.md delete mode 100644 docs/admin/getting-started/container/docker-compose/keycloak.md create mode 100644 docs/admin/getting-started/container/docker-compose/production-considerations.md delete mode 100644 docs/admin/getting-started/container/docker-compose/production-setup-consideration.md delete mode 100644 docs/admin/getting-started/container/docker-compose/verify-SSL-certification.md create mode 100644 docs/admin/getting-started/container/docker-compose/verify-tls-certificates.md create mode 100644 docs/admin/getting-started/container/docker-compose/volume-permissions.md diff --git a/docs/admin/getting-started/container/docker-compose/_category_.json b/docs/admin/getting-started/container/docker-compose/_category_.json index 0f0aa612..545ef39c 100644 --- a/docs/admin/getting-started/container/docker-compose/_category_.json +++ b/docs/admin/getting-started/container/docker-compose/_category_.json @@ -1,4 +1,5 @@ { - "label": "Docker-Compose", - "position": 1 + "label": "Docker Compose", + "position": 1, + "description": "Deploy OpenCloud using Docker Compose with Traefik or an external reverse proxy" } diff --git a/docs/admin/getting-started/container/docker-compose/docker-external-proxy.md b/docs/admin/getting-started/container/docker-compose/docker-external-proxy.md index 54783ad9..314df874 100644 --- a/docs/admin/getting-started/container/docker-compose/docker-external-proxy.md +++ b/docs/admin/getting-started/container/docker-compose/docker-external-proxy.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 id: external-proxy title: Behind External Proxy description: How to run OpenCloud behind an external Nginx proxy with Certbot (manual setup). @@ -10,6 +10,10 @@ draft: false This guide walks you through setting up OpenCloud behind an external Nginx reverse proxy with Let's Encrypt certificates using `certbot certonly --webroot`. +:::note Using Traefik Instead? +If you don't have an existing reverse proxy or prefer to let Traefik manage certificates automatically, see [Docker Compose with Integrated Traefik](./integrated-traefik.md) instead. +::: + ## Requirements - A public server with a static IP @@ -139,16 +143,20 @@ WOPISERVER_DOMAIN=wopiserver.YOUR.DOMAIN The initial Admin password is mandatory for security reasons. -For production releases, please refer to the considerations outlined in the Docker Compose base instructions: - -[production setup consideration](./docker-compose-base#production-setup-consideration) - Start the docker compose setup ```bash docker compose up -d ``` +## Next Steps + +For production deployments, review [Production Considerations](./production-considerations.md) for: + +- Persistent volumes and data recovery +- Image version pinning +- Permission and ownership best practices + ## Set Up the Final Nginx Reverse Proxy ### Remove the temporary certbot config diff --git a/docs/admin/getting-started/container/docker-compose/index.md b/docs/admin/getting-started/container/docker-compose/index.md new file mode 100644 index 00000000..6e02c730 --- /dev/null +++ b/docs/admin/getting-started/container/docker-compose/index.md @@ -0,0 +1,57 @@ +--- +sidebar_position: 1 +id: docker-compose-overview +title: Docker Compose Overview +description: Choose your Docker Compose deployment architecture for OpenCloud +--- + +# Docker Compose Deployment + +This section guides you through deploying OpenCloud using Docker Compose. We support two main deployment architectures, suitable for different infrastructure scenarios. + +## Choose Your Deployment Path + +### 1. **Integrated Traefik** (Recommended for most users) + +Use the built-in Traefik reverse proxy and automatic Let's Encrypt SSL certificates. This is the standard, recommended path for new deployments. + +**Best for:** + +- Standalone servers +- No existing reverse proxy infrastructure +- Simple, self-contained setup + +[Get Started with Integrated Traefik →](./integrated-traefik.md) + +### 2. **Behind External Proxy** (For existing infrastructure) + +Deploy OpenCloud behind your own Nginx, HAProxy, or other reverse proxy. Choose this if you already have a reverse proxy in place or prefer to manage it separately. + +**Best for:** + +- Multi-service environments +- Existing reverse proxy infrastructure +- Complex networking requirements + +[Deploy Behind External Proxy →](./external-proxy.md) + +## Next Steps + +After choosing and completing your deployment: + +- **[Production Setup Considerations](./production-considerations.md)** – Persistent storage, backups, image versions +- **[Verify TLS Certificates](./verify-tls-certificates.md)** – Validate your SSL setup +- **[Configure Authentication](../../../configuration/authentication-and-user-management/)** – Users, authentication, and optional Keycloak integration + +## Project Structure + +Both deployment paths use the same underlying composition of services: + +- OpenCloud server +- Collabora Online Editor (optional) +- WOPI Server +- Database +- Object Storage (MinIO) +- Optional: Traefik (integrated path) or your external proxy (external path) + +Choose the path that best matches your infrastructure and requirements. diff --git a/docs/admin/getting-started/container/docker-compose/docker-compose-base.md b/docs/admin/getting-started/container/docker-compose/integrated-traefik.md similarity index 58% rename from docs/admin/getting-started/container/docker-compose/docker-compose-base.md rename to docs/admin/getting-started/container/docker-compose/integrated-traefik.md index 4daa5a2e..aec9ef49 100644 --- a/docs/admin/getting-started/container/docker-compose/docker-compose-base.md +++ b/docs/admin/getting-started/container/docker-compose/integrated-traefik.md @@ -1,17 +1,22 @@ --- -sidebar_position: 1 -id: docker-compose-base -title: Docker Compose -description: Full-blown featureset including web office. -draft: false +sidebar_position: 2 +id: docker-compose-integrated-traefik +title: Docker Compose with Integrated Traefik +description: Get started with OpenCloud using Docker Compose and the integrated Traefik reverse proxy with automatic SSL certificates --- -# OpenCloud with Docker Compose +# OpenCloud with Docker Compose + Integrated Traefik -Install an internet-facing OpenCloud instance with SSL certificates using Docker Compose. +Install an internet-facing OpenCloud instance with automatic SSL certificates using Docker Compose's integrated Traefik reverse proxy. + +This is the **recommended deployment path** for most new OpenCloud installations. Traefik automatically manages Let's Encrypt SSL certificates, eliminating the need to manage a separate reverse proxy. This installation guide is written for Ubuntu and Debian systems. The software can also be installed on other Linux distributions, but commands and package managers may differ. +:::note Not using Traefik? +If you already have an external reverse proxy (Nginx, HAProxy, etc.) or prefer to manage it separately, see [Deploy Behind External Proxy](./external-proxy.md) instead. +::: + ## Prerequisites - Four domains pointing to your server: @@ -60,7 +65,7 @@ git clone https://github.com/opencloud-eu/opencloud-compose.git ## Configure the .env File for Staging Certificates -Before requesting real SSL certificates, it is recommended to test the setup using Let's Encrypt’s staging environment. +Before requesting real SSL certificates, it is recommended to test the setup using Let's Encrypt's staging environment. ### Navigate to the OpenCloud configuration folder @@ -140,3 +145,28 @@ docker compose up -d ``` This will start all required services in the background. + +## Verify Your Deployment + +After starting OpenCloud, verify that services are running and SSL certificates were issued: + +1. Check the [TLS/SSL certificates are valid](./verify-tls-certificates.md) +2. Log in to OpenCloud: `https://cloud.YOUR.DOMAIN` + - Username: `admin` + - Password: (the password you set in `.env`) + +## Next Steps + +- **[Verify TLS Certificates](./verify-tls-certificates.md)** – Validate staging certificates and switch to production +- **[Production Setup Considerations](./production-considerations.md)** – Persistent storage, backups, and production best practices +- **[Configure Keycloak](./keycloak-deployment.md)** (optional) – Add Keycloak for enterprise identity management +- **[Configure Authentication](../../../configuration/authentication-and-user-management/)** – User management and identity provider integration + +## Troubleshooting + +If you encounter issues: + +1. Check Docker logs: `docker compose logs` +2. Verify domain DNS records point to your server +3. Ensure firewall allows HTTP (80) and HTTPS (443) +4. See [Common Issues & Help](../../../resources/common-issues) diff --git a/docs/admin/getting-started/container/docker-compose/keycloak-deployment.md b/docs/admin/getting-started/container/docker-compose/keycloak-deployment.md new file mode 100644 index 00000000..583cc368 --- /dev/null +++ b/docs/admin/getting-started/container/docker-compose/keycloak-deployment.md @@ -0,0 +1,151 @@ +--- +sidebar_position: 6 +id: docker-compose-keycloak-deployment +title: Enable Keycloak Integration +description: Add Keycloak identity management to your Docker Compose OpenCloud deployment +draft: false +--- + +# Keycloak Integration with Docker Compose + +This guide explains how to enable Keycloak as an identity provider (IdP) for your Docker Compose OpenCloud deployment. This provides enterprise-grade user and access management. + +:::note +This page covers **deployment setup only**. For detailed Keycloak configuration, user management, and integration patterns, see the [Keycloak Configuration Guide](../../../configuration/authentication-and-user-management/keycloak.md). +::: + +## Prerequisites + +- An existing OpenCloud Docker Compose deployment +- Understanding of [Keycloak as an identity provider](../../../configuration/authentication-and-user-management/keycloak.md) + +## Enable Keycloak in `.env` + +Edit your environment configuration file: + +```bash +cd opencloud-compose +nano .env +``` + +Add or uncomment the following lines to enable **Keycloak with integrated LDAP**: + +```bash +# Enable Keycloak + LDAP services +COMPOSE_FILE=docker-compose.yml:idm/ldap-keycloak.yml:traefik/opencloud.yml:traefik/ldap-keycloak.yml + +# Keycloak domain (without https://) +KEYCLOAK_DOMAIN=keycloak.YOUR.DOMAIN + +# Keycloak admin credentials +KEYCLOAK_ADMIN=admin +KEYCLOAK_ADMIN_PASSWORD=ChangeMeToASecurePassword +``` + +### Available Docker Compose configurations + +The `opencloud-compose` repository provides several idm (Identity Management) options: + +| Configuration | Use Case | +| ----------------------- | -------------------------------------------------------------- | +| `idm/ldap-keycloak.yml` | Keycloak with integrated OpenLDAP (recommended for new setups) | +| `idm/keycloak.yml` | Keycloak standalone without LDAP | +| `idm/openldap.yml` | OpenLDAP only (for external IdP integration) | + +Choose the configuration that matches your authentication infrastructure. + +## Start OpenCloud with Keycloak + +After updating `.env`, start the deployment: + +```bash +docker compose up -d +``` + +Docker will pull and start the Keycloak container along with OpenCloud services. + +### Wait for services to initialize + +Keycloak may take a minute or two to start. Monitor the logs: + +```bash +docker compose logs keycloak +``` + +Look for messages indicating Keycloak is ready to accept connections. + +## Access Keycloak + +Once running, access the Keycloak admin console: + +```bash +https://keycloak.YOUR.DOMAIN +``` + +Log in with the credentials you set in `.env`: + +- **Username:** `admin` (or your `KEYCLOAK_ADMIN` value) +- **Password:** Your `KEYCLOAK_ADMIN_PASSWORD` + +## Next Steps + +### 1. Configure Keycloak for OpenCloud + +The Docker Compose setup auto-imports a base configuration for OpenCloud via `keycloak-realm.dist.json`. However, you'll likely need to: + +- Create users and assign roles +- Configure authentication flows +- Set up LDAP federation (if using `ldap-keycloak.yml`) +- Configure OIDC client settings + +See [Keycloak Configuration & Integration Guide](../../../configuration/authentication-and-user-management/keycloak.md) for detailed instructions. + +### 2. Create Users in Keycloak + +Follow the guide [Adding Users with Keycloak](../../../configuration/authentication-and-user-management/keycloak-user.md) to: + +- Assign admin roles +- Create users with standard or guest permissions +- Enable self-registration + +### 3. Update OpenCloud Configuration + +Configure OpenCloud to use Keycloak as the identity provider. This typically involves setting OIDC-related environment variables. See the [Keycloak Integration documentation](../../../configuration/authentication-and-user-management/keycloak.md) for details. + +## Troubleshooting + +### Keycloak won't start + +Check container logs: + +```bash +docker compose logs keycloak +``` + +Common issues: + +- Insufficient disk space or memory +- Port conflicts (Keycloak uses port 8080 internally) +- Database connection issues + +### Can't access Keycloak admin console + +Verify: + +1. The domain `keycloak.YOUR.DOMAIN` resolves to your server +2. Traefik has successfully assigned SSL certificates (check via `docker compose logs traefik`) +3. Keycloak container is running: `docker compose ps keycloak` + +### LDAP federation issues + +If using `idm/ldap-keycloak.yml`: + +1. Verify OpenLDAP is running: `docker compose ps openldap` +2. Check Keycloak logs for LDAP connection errors +3. Verify LDAP user federation is configured correctly in Keycloak admin console + +## See Also + +- **[Full Keycloak Integration Guide](../../../configuration/authentication-and-user-management/keycloak.md)** – Configuration, modes, and advanced setup +- **[User Management with Keycloak](../../../configuration/authentication-and-user-management/keycloak-user.md)** – Creating users and managing roles +- **[Production Considerations](./production-considerations.md)** – Backup and production best practices diff --git a/docs/admin/getting-started/container/docker-compose/keycloak.md b/docs/admin/getting-started/container/docker-compose/keycloak.md deleted file mode 100644 index 03e40ec4..00000000 --- a/docs/admin/getting-started/container/docker-compose/keycloak.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -sidebar_position: 5 -id: keycloak -title: Keycloak -description: 'OpenCloud with Keycloak.' -draft: true ---- - -# Keycloak Integration - -## Enable Keycloak - -To enable Keycloak for identity and access management, uncomment the following lines in your `.env` file - -```env -# Enable services -COMPOSE_FILE=docker-compose.yml:idm/ldap-keycloak.yml:traefik/opencloud.yml:traefik/ldap-keycloak.yml -# Your public keycloak domain without protocol -KEYCLOAK_DOMAIN=your-keycloak-domain.example.com -# Admin user login name. Defaults to "kcadmin". -KEYCLOAK_ADMIN= -# Admin user login password. Defaults to "admin". -KEYCLOAK_ADMIN_PASSWORD= -``` - -The Docker Compose file `idm/ldap-keycloak.yml` contains the complete configuration for each component. - -Keycloak is configured during startup by importing the `keycloak-realm.dist.json` file. This file contains the configuration for the OpenCloud realm, including client settings, roles, and user federation. This file is located in the `config/keycloak` directory of the `opencloud-compose` repository. - -## Starting OpenCloud - -After starting OpenCloud, Keycloak will be available at - -```bash -https://keycloak.your.domain -``` - -## Initial User Setup in Keycloak - -Once Keycloak is running - -### Open your browser and go to - -```bash -https://keycloak.your.domain -``` - -Keycloak dashboard - -### Log in with the admin credentials (default is admin / admin) - -Keycloak login - -### In the top-left dropdown (labeled Keycloak), switch to the OpenCloud realm - -Top left dropdown menue - -### Navigate to the "Users" section and click "Add user" - -User section - -- Fill in a username -- Optionally add email, first/last name -- Click "Create" - Fill in userdata - -### Go to the "Credentials" tab - -- Click "Set password" - Credentials -
-- Set a temporary password -- Enable "Temporary" to force password change on first login (optional) -- Click "Save" - Set password - -### Go to the "Role Mapping" tab - -Role mapping - -- Click "Assign role" - Assign role - -- In the dialog, click "Filter by realm roles" - Filter by realm roles - -- Choose the appropriate role (e.g., user, admin, etc.) -- Click "Assign" - Realm roles - -The user can now log in via OpenCloud using the Keycloak credentials. diff --git a/docs/admin/getting-started/container/docker-compose/production-considerations.md b/docs/admin/getting-started/container/docker-compose/production-considerations.md new file mode 100644 index 00000000..6fe8d6e2 --- /dev/null +++ b/docs/admin/getting-started/container/docker-compose/production-considerations.md @@ -0,0 +1,104 @@ +--- +sidebar_position: 4 +id: docker-compose-production-considerations +title: Production Considerations +description: Best practices and recommendations for production OpenCloud deployments with Docker Compose +--- + +# Production Setup Considerations + +This guide outlines essential best practices and configurations for running OpenCloud in a production environment with Docker Compose. + +:::caution Production Setup Recommended +By default, OpenCloud stores configuration and data inside internal Docker volumes. +This works fine for local development or quick evaluations — but is not suitable for production environments. +::: + +## Mount Persistent Volumes + +For production deployments, you should mount persistent local directories for configuration and data. This ensures: + +- **Data durability** – Configuration and data persist across container restarts +- **Easier backups and recovery** – Access files directly from the host +- **Full control over storage location and permissions** – Meet organizational compliance requirements + +### Update your `.env` file with custom paths + +Edit your environment configuration to specify local mount points: + +```bash +nano .env +``` + +Add or uncomment these variables: + +```bash +OC_CONFIG_DIR=/your/local/path/opencloud/config +OC_DATA_DIR=/your/local/path/opencloud/data +``` + +Replace `/your/local/path/opencloud` with your desired location (e.g., `/opt/opencloud` or `/mnt/data/opencloud`). + +### Ensure proper folder ownership and permissions + +Create the directories and set correct ownership for the container user (UID/GID 1000:1000 by default): + +```bash +sudo mkdir -p /your/local/path/opencloud/{config,data} +sudo chown -R 1000:1000 /your/local/path/opencloud +sudo chmod -R 0700 /your/local/path/opencloud +``` + +If these variables are not set, Docker will use internal volumes. These volumes may be removed when containers are deleted, which means your configuration and data may be lost. This setup is therefore not recommended for production use. + +:::caution Security Warning + +The user with UID 1000 on your host system will have full access to these mounted directories. This means that any local user account with this ID can read, modify, or delete OpenCloud config and data files. + +This can pose a security risk in shared or multi-user environments. Make sure to implement proper user and permission management and consider isolating access to these directories. + +For more details on volume permissions, see [Volume Permissions and UID/GID Management](./volume-permissions.md). + +::: + +## Pin Container Images for Stability + +To avoid accidentally upgrading to versions that may contain breaking changes, explicitly specify the container image version in your `.env` file: + +```bash +OC_DOCKER_IMAGE=opencloudeu/opencloud +OC_DOCKER_TAG=2 +``` + +**Recommended approach:** + +- Use major version tags (e.g., `2`, `3`) for stable production releases +- Test minor/patch updates in a staging environment before production +- Avoid using `latest` tag in production, as it may introduce unexpected changes + +This ensures your deployment always uses a stable, tested release instead of automatically pulling newer versions. + +## Backup and Recovery Strategy + +With persistent volumes in place, implement a backup strategy: + +1. **Regular snapshots** of `OC_CONFIG_DIR` and `OC_DATA_DIR` +2. **Database backups** (typically in `OC_DATA_DIR`) +3. **Off-site storage** for disaster recovery +4. **Test recovery procedures** regularly + +Refer to your system administration practices for backup tools (rsync, tar, Restic, etc.). + +## Environment and SSL Certificates + +Once your staging setup is working: + +1. Switch to **Let's Encrypt production certificates** – See [Verify TLS Certificates](./verify-tls-certificates.md#apply-a-real-ssl-certificate) +2. Update **security headers and policies** in your reverse proxy +3. Enable **HSTS (HTTP Strict Transport Security)** for production domains + +## Next Steps + +- **[Verify TLS Certificates](./verify-tls-certificates.md)** – Switch from staging to production certificates +- **[Volume Permissions Guide](./volume-permissions.md)** – Detailed UID/GID and permission management +- **[Maintenance & Monitoring](../../maintenance/)** – Logging and system health checks diff --git a/docs/admin/getting-started/container/docker-compose/production-setup-consideration.md b/docs/admin/getting-started/container/docker-compose/production-setup-consideration.md deleted file mode 100644 index 98486e2c..00000000 --- a/docs/admin/getting-started/container/docker-compose/production-setup-consideration.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -sidebar_position: 3 -id: production-setup-consideration -title: Production Setup Consideration -description: 'OpenCloud Production Setup Consideration' -draft: true ---- - -# Production Setup Consideration - -:::caution Production Setup Recommended -By default, OpenCloud stores configuration and data inside internal Docker volumes. -This works fine for local development or quick evaluations — but is not suitable for production environments. -::: - -## Mount Persistent Volumes - -For production deployments, you should mount persistent local directories for configuration and data. This ensures: - -- Data durability -- Easier backups and recovery -- Full control over storage location and permissions - -### Update your `.env` file with custom paths - -```bash -OC_CONFIG_DIR=/your/local/path/opencloud/config -OC_DATA_DIR=/your/local/path/opencloud/data -``` - -### Set your email for SSL certification - -```bash -TRAEFIK_ACME_MAIL=your@email.com -``` - -:::tip Folder Permissions - -### Ensure these folders exist and are owned by user and group 1000:1000, which the Docker containers use by default - -```bash -sudo mkdir -p /your/local/path/opencloud/{config,data} -sudo chown -R 1000:1000 /your/local/path/opencloud -``` - -::: - -If these variables are not set, Docker will use internal volumes. -These volumes may be removed when containers are deleted, which means your configuration and data may be lost. This setup is therefore not recommended for production use. - -:::caution Security Warning - -The user with UID 1000 on your host system will have full access to these mounted directories. This means that any local user account with this ID can read, modify, or delete OpenCloud config and data files. - -This can pose a security risk in shared or multi-user environments. Make sure to implement proper user and permission management and consider isolating access to these directories. - -::: - -## Use production release container - -To avoid accidentally upgrading to versions that may contain breaking changes, you should explicitly specify the container image and version in your .env file. - -```bash -OC_DOCKER_IMAGE=opencloudeu/opencloud -OC_DOCKER_TAG=2 -``` - -This ensures that your deployment always uses a stable production release instead of automatically pulling newer versions. diff --git a/docs/admin/getting-started/container/docker-compose/verify-SSL-certification.md b/docs/admin/getting-started/container/docker-compose/verify-SSL-certification.md deleted file mode 100644 index 7fa9acde..00000000 --- a/docs/admin/getting-started/container/docker-compose/verify-SSL-certification.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -sidebar_position: 4 -id: verify-SSL-certification -title: Verify SSL Certification -description: 'Verify SSL Certification in OpenCloud' -draft: true ---- - -# Verify SSL Certification - -## After starting OpenCloud, verify that the SSL certificates were issued correctly - -Open the following URL in your web browser: - -```bash -https://cloud.YOUR.DOMAIN -``` - -Because the setup currently uses Let's Encrypt staging certificates, your browser will show a security warning. This is expected, as staging certificates are not trusted by browsers. - -The same warning may appear for the other domains you configured. - -Example in the Chrome browser: - -Certificate Details - -- Check the certificate details to confirm that the certificate was issued by Let's Encrypt Staging. - - Certificate Details - Certificate Details - -## Apply a Real SSL Certificate - -Once the staging certificate works correctly, you can switch to a production SSL certificate. - -### Stop Docker Compose - -Stop the running containers: - -```bash -docker compose down -``` - -### Remove old staging certificates - -Delete the previously generated staging certificates: - -```bash -rm -r certs -``` - -If you changed volume names or paths, adjust this command accordingly. - -### Disable staging mode in `.env` - -Open the environment file: - -```bash -nano .env -``` - -Comment the staging server: - -```bash -# TRAEFIK_ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory -``` - -### Restart OpenCloud with a real SSL certificate - -Start the containers again: - -```bash -docker compose up -d -``` - -OpenCloud will now request trusted production certificates from Let's Encrypt. - -After a short moment, visiting the following URL should show a secure HTTPS connection: - -Certificate Details - -## Log into OpenCloud - -Open a browser and visit: - -```bash -https://cloud.YOUR.DOMAIN -``` - -Login with: - -Username: `admin` - -Password: (the password you configured in the .env file) - -Admin general - -## Troubleshooting - -If you encounter any issues during the setup process, check the troubleshooting guide: -[Common Issues & Help](../../../resources/common-issues) diff --git a/docs/admin/getting-started/container/docker-compose/verify-tls-certificates.md b/docs/admin/getting-started/container/docker-compose/verify-tls-certificates.md new file mode 100644 index 00000000..a992dd48 --- /dev/null +++ b/docs/admin/getting-started/container/docker-compose/verify-tls-certificates.md @@ -0,0 +1,171 @@ +--- +sidebar_position: 5 +id: docker-compose-verify-tls +title: Verify TLS/SSL Certificates +description: Validate SSL certificates and migrate from Let's Encrypt staging to production +--- + +# Verify TLS and SSL Certificates + +After starting OpenCloud with Docker Compose and Traefik, verify that SSL certificates were issued correctly and switch from staging to production certificates when ready. + +:::note +This guide applies to the [integrated Traefik deployment](./integrated-traefik.md). For external proxy setups, see [Behind External Proxy](./external-proxy.md). +::: + +## Verify Staging Certificates + +By default, the setup uses **Let's Encrypt staging certificates** for testing. These are not trusted by browsers but prove that the DNS and certificate generation workflow is correct. + +### Open your domain in a web browser + +Open the following URL: + +```bash +https://cloud.YOUR.DOMAIN +``` + +Because the setup currently uses Let's Encrypt staging certificates, your browser will show a security warning. **This is expected and normal for the staging environment.** + +The same warning may appear for the other configured domains. + +### Example in Chrome + +Click on the lock icon to view certificate details: + +Certificate Details + +Expand the certificate information to confirm it was issued by "Let's Encrypt Staging": + +Certificate Details + +Certificate Details Subordinate CA + +:::success Staging Certificate Success +If you see "Let's Encrypt Staging" as the issuer, the certificate generation is working correctly. You can now safely switch to production certificates. +::: + +## Apply a Real SSL Certificate + +Once the staging certificate works correctly, you can switch to production SSL certificates from Let's Encrypt. + +### Stop Docker Compose + +```bash +docker compose down +``` + +### Remove old staging certificates + +Delete the previously generated staging certificates: + +```bash +rm -r certs +``` + +:::warning +If you changed volume names or paths in your `.env` file, adjust this command to match your certificate directory. +::: + +### Disable staging mode in `.env` + +Open the environment file: + +```bash +nano .env +``` + +Comment out or remove the staging server line: + +```bash +# TRAEFIK_ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory +``` + +Save the file. + +### Restart OpenCloud with production certificates + +Start the containers again: + +```bash +docker compose up -d +``` + +Traefik will now request trusted production certificates from Let's Encrypt. + +### Wait for certificate generation + +Certificate generation may take a few moments. Check the logs: + +```bash +docker compose logs traefik +``` + +Look for messages indicating successful certificate generation. + +### Verify production certificates + +After a short moment, visiting your domain should show a secure HTTPS connection: + +Secure Connection + +The lock icon should show "Secure" (green lock) with "Let's Encrypt Authority X3" or similar as the issuer. + +## Log into OpenCloud + +Once certificates are verified: + +1. Open your domain in a browser: + +```bash +https://cloud.YOUR.DOMAIN +``` + +2. Log in with your admin credentials: + - **Username:** `admin` + - **Password:** (the password you configured in the `.env` file) + +OpenCloud Login + +## Troubleshooting + +### Certificate generation fails + +**Check Traefik logs:** + +```bash +docker compose logs traefik +``` + +Look for error messages about ACME challenges. + +### DNS issues + +Ensure your domain correctly points to your server: + +```bash +nslookup cloud.YOUR.DOMAIN +``` + +The result should match your server's IP address. + +### Port 80/443 not accessible + +Verify firewall rules allow: + +- HTTP (port 80) – Required for ACME challenge +- HTTPS (port 443) – Required for OpenCloud access + +### Certificate not updating + +If Traefik fails to renew certificates: + +1. Check available disk space +2. Verify ACME email is correct in `.env` +3. Review Traefik configuration in your Docker Compose setup + +## Next Steps + +- **[Production Considerations](./production-considerations.md)** – Persistent storage and production best practices +- **[Configure Keycloak](./keycloak-deployment.md)** (optional) – Add enterprise identity management +- **[Maintenance & Monitoring](../../maintenance/)** – System health and logging diff --git a/docs/admin/getting-started/container/docker-compose/volume-permissions.md b/docs/admin/getting-started/container/docker-compose/volume-permissions.md new file mode 100644 index 00000000..c33defe9 --- /dev/null +++ b/docs/admin/getting-started/container/docker-compose/volume-permissions.md @@ -0,0 +1,245 @@ +--- +sidebar_position: 7 +id: docker-compose-volume-permissions +title: Volume Permissions and UID/GID Management +description: Understanding and managing filesystem permissions for OpenCloud Docker volumes +--- + +# Volume Permissions and UID/GID Management + +This guide explains how to properly configure filesystem permissions for OpenCloud's persistent volumes in Docker Compose deployments. Understanding UID/GID mappings is crucial for production deployments with mounted volumes. + +## Default Container User + +OpenCloud containers run as a non-root user with: + +- **UID (User ID):** 1000 +- **GID (Group ID):** 1000 + +This is the user that reads and writes to all data, configuration, and cache directories within the container. + +## Mount Point Permissions + +When you mount directories from your host system into the container, the container's UID 1000 must have proper read/write access. + +### Correct Setup + +```bash +# Create directories +sudo mkdir -p /your/local/path/opencloud/{config,data} + +# Set ownership to UID/GID 1000:1000 +sudo chown -R 1000:1000 /your/local/path/opencloud + +# Set appropriate permissions (owner can read/write/execute, others cannot) +sudo chmod -R 0700 /your/local/path/opencloud +``` + +Directory structure should look like: + +``` +/your/local/path/opencloud/ +├── config/ (UID 1000 owner, mode 0700) +│ ├── opencloud.config.php +│ ├── redis/ +│ └── nginx/ +└── data/ (UID 1000 owner, mode 0700) + ├── database/ + ├── files/ + └── objectstorage/ +``` + +### Verifying permissions + +Check that directories are owned by 1000:1000: + +```bash +ls -ln /your/local/path/opencloud/ +# Example output: +# drwx------ 5 1000 1000 4096 Jan 15 10:30 config +# drwx------ 8 1000 1000 4096 Jan 16 14:22 data +``` + +## Understanding UID Mapping + +### Host user with UID 1000 + +If your host system has a user with UID 1000 (e.g., the first non-root user created): + +```bash +id myuser +# Output: uid=1000(myuser) gid=1000(myuser) groups=1000(myuser) +``` + +That user can directly access the mounted directories: + +```bash +ls /your/local/path/opencloud/config +cd /your/local/path/opencloud/data +``` + +This is the **most common case** and requires minimal configuration. + +### UID mismatch scenarios + +**Problem:** Your host system's UID 1000 is assigned to a different user (or doesn't exist). + +```bash +cat /etc/passwd | grep 1000 +# (empty or shows different user) +``` + +**Solution:** Create a dedicated service user or adjust permissions: + +```bash +# Option 1: Create a dedicated user for OpenCloud +sudo useradd -u 1000 -m -s /usr/sbin/nologin opencloud + +# Then change ownership +sudo chown -R opencloud:opencloud /your/local/path/opencloud + +# Option 2: Use numeric IDs in chown +sudo chown -R 1000:1000 /your/local/path/opencloud +``` + +## Permission Modes Explained + +### Recommended: 0700 (rwx------) + +```bash +sudo chmod -R 0700 /your/local/path/opencloud +``` + +- Owner (UID 1000): read, write, execute +- Group members: no access +- Others: no access + +**Use case:** Maximum security; only the container user can access. + +### More permissive: 0750 (rwxr-x---) + +```bash +sudo chmod -R 0750 /your/local/path/opencloud +``` + +- Owner: read, write, execute +- Group members: read, execute +- Others: no access + +**Use case:** Allows other group members to read (useful for backups, monitoring). + +### Caution: 0755 (rwxr-xr-x) + +```bash +sudo chmod -R 0755 /your/local/path/opencloud +``` + +- Everyone can read and list directories + +**Warning:** Not recommended for data directories containing sensitive information. + +## Bind Mounts vs Named Volumes + +### Bind Mounts (Recommended for persistent data) + +```bash +# In .env or docker-compose override +OC_CONFIG_DIR=/your/local/path/opencloud/config +OC_DATA_DIR=/your/local/path/opencloud/data +``` + +**Advantages:** + +- Full control over permissions and ownership +- Easy to backup +- Direct host filesystem access + +**You must manually manage permissions.** + +### Named Volumes (Docker-managed) + +If not set, Docker creates automatic volumes: + +```bash +# Volumes are stored in /var/lib/docker/volumes/ +docker volume ls +``` + +**Advantages:** + +- Docker manages permissions automatically +- Docker handles backup/restore + +**Disadvantages:** + +- Harder to access directly +- Less control over ownership +- Not recommended for production + +## Troubleshooting Permission Issues + +### "Permission denied" errors in container + +If OpenCloud container can't read/write: + +```bash +# Check container can see files +docker compose exec opencloud ls -la /var/opencloud/config + +# If permission denied, check host ownership +ls -ln /your/local/path/opencloud/config + +# Fix: Change ownership +sudo chown -R 1000:1000 /your/local/path/opencloud +``` + +### Cannot write after mounting + +```bash +# Error: "Read-only file system" +# Solution: Ensure directory is writable +sudo chmod u+w /your/local/path/opencloud/{config,data} +``` + +### Backup/restore permission issues + +When restoring from backup: + +```bash +# After extracting backup, fix permissions +sudo chown -R 1000:1000 /your/local/path/opencloud +sudo chmod -R 0700 /your/local/path/opencloud +``` + +## Security Considerations + +:::caution +UID 1000 on your host system will have **full read/write access** to OpenCloud data. + +In multi-user or shared hosting environments: + +1. Isolate the host user (e.g., dedicated service account) +2. Restrict SSH/shell access appropriately +3. Use additional filesystem-level security (SELinux, AppArmor) +4. Regularly audit file access + + ::: + +## Environment Variables for Persistence + +```bash +# In .env file +OC_CONFIG_DIR=/your/local/path/opencloud/config +OC_DATA_DIR=/your/local/path/opencloud/data +OC_LOG_DIR=/your/local/path/opencloud/logs + +# Ensure these directories exist with correct permissions +``` + +If these variables are not set, Docker will use unnamed volumes that persist only as long as containers are not removed. + +## See Also + +- **[Production Considerations](./production-considerations.md)** – Volume mounting setup +- **[Docker documentation on volumes](https://docs.docker.com/storage/volumes/)** +- **[Linux permission quick reference](https://en.wikipedia.org/wiki/File-system_permissions)** From 7049a9881c5f9a245c3884e43bea13f1794b7b9f Mon Sep 17 00:00:00 2001 From: Heiko Pohl Date: Thu, 19 Mar 2026 10:25:58 +0100 Subject: [PATCH 3/4] changes in admin docs --- ...ated-traefik.md => docker-compose-base.md} | 9 +- .../docker-compose/volume-permissions.md | 2 +- .../docker-compose/docker-compose-base.md | 169 +++--------- .../docker-compose/docker-external-proxy.md | 15 +- .../container/docker-compose/keycloak.md | 2 +- .../production-setup-consideration.md | 68 +++++ .../verify-SSL-certification.md | 101 ++++++++ .../docker-compose/volume-permissions.md | 245 ++++++++++++++++++ 8 files changed, 459 insertions(+), 152 deletions(-) rename docs/admin/getting-started/container/docker-compose/{integrated-traefik.md => docker-compose-base.md} (95%) create mode 100644 versioned_docs/version-4.0/admin/getting-started/container/docker-compose/production-setup-consideration.md create mode 100644 versioned_docs/version-4.0/admin/getting-started/container/docker-compose/verify-SSL-certification.md create mode 100644 versioned_docs/version-4.0/admin/getting-started/container/docker-compose/volume-permissions.md diff --git a/docs/admin/getting-started/container/docker-compose/integrated-traefik.md b/docs/admin/getting-started/container/docker-compose/docker-compose-base.md similarity index 95% rename from docs/admin/getting-started/container/docker-compose/integrated-traefik.md rename to docs/admin/getting-started/container/docker-compose/docker-compose-base.md index aec9ef49..dfda07f4 100644 --- a/docs/admin/getting-started/container/docker-compose/integrated-traefik.md +++ b/docs/admin/getting-started/container/docker-compose/docker-compose-base.md @@ -1,8 +1,9 @@ --- -sidebar_position: 2 -id: docker-compose-integrated-traefik -title: Docker Compose with Integrated Traefik -description: Get started with OpenCloud using Docker Compose and the integrated Traefik reverse proxy with automatic SSL certificates +sidebar_position: 1 +id: docker-compose-base +title: Docker Compose Base +description: Full-blown featureset including web office. +draft: false --- # OpenCloud with Docker Compose + Integrated Traefik diff --git a/docs/admin/getting-started/container/docker-compose/volume-permissions.md b/docs/admin/getting-started/container/docker-compose/volume-permissions.md index c33defe9..a1a55284 100644 --- a/docs/admin/getting-started/container/docker-compose/volume-permissions.md +++ b/docs/admin/getting-started/container/docker-compose/volume-permissions.md @@ -37,7 +37,7 @@ sudo chmod -R 0700 /your/local/path/opencloud Directory structure should look like: -``` +```bash /your/local/path/opencloud/ ├── config/ (UID 1000 owner, mode 0700) │ ├── opencloud.config.php diff --git a/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/docker-compose-base.md b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/docker-compose-base.md index 9efb8037..dfda07f4 100644 --- a/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/docker-compose-base.md +++ b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/docker-compose-base.md @@ -1,16 +1,22 @@ --- sidebar_position: 1 id: docker-compose-base -title: Docker Compose +title: Docker Compose Base description: Full-blown featureset including web office. draft: false --- -# OpenCloud with Docker Compose +# OpenCloud with Docker Compose + Integrated Traefik -Install a internet facing OpenCloud with SSL certification with Docker Compose. +Install an internet-facing OpenCloud instance with automatic SSL certificates using Docker Compose's integrated Traefik reverse proxy. -This installation documentation is for Ubuntu and Debian systems. The software can also be installed on other Linux distributions, but the commands and package managers may differ. +This is the **recommended deployment path** for most new OpenCloud installations. Traefik automatically manages Let's Encrypt SSL certificates, eliminating the need to manage a separate reverse proxy. + +This installation guide is written for Ubuntu and Debian systems. The software can also be installed on other Linux distributions, but commands and package managers may differ. + +:::note Not using Traefik? +If you already have an external reverse proxy (Nginx, HAProxy, etc.) or prefer to manage it separately, see [Deploy Behind External Proxy](./external-proxy.md) instead. +::: ## Prerequisites @@ -60,7 +66,7 @@ git clone https://github.com/opencloud-eu/opencloud-compose.git ## Configure the .env File for Staging Certificates -Before requesting real SSL certificates, test the setup with Let's Encrypt’s staging environment. +Before requesting real SSL certificates, it is recommended to test the setup using Let's Encrypt's staging environment. ### Navigate to the OpenCloud configuration folder @@ -78,16 +84,16 @@ cp .env.example .env The repository includes .env.example as a template with default settings and documentation. Your actual .env file is excluded from version control (via .gitignore) to prevent accidentally committing sensitive information like passwords and domain-specific settings. ::: -Edit the `.env` file with the editor of your choice: +## Modify these settings + +### Edit the `.env` file with the editor of your choice -### In our example we use nano +In our example we use nano ```bash nano .env ``` -## Modify these settings - ### Disable insecure mode ```bash @@ -123,65 +129,13 @@ TRAEFIK_ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory ### Set your deployment options -For Example without Collabora: +Example configuration without Collabora: ```bash COMPOSE_FILE=docker-compose.yml:traefik/opencloud.yml ``` -Save and exit. - -### Production Setup Consideration - -:::caution Production Setup Recommended -By default, OpenCloud stores configuration and data inside internal Docker volumes. -This works fine for local development or quick evaluations — but is not suitable for production environments. -::: - -#### Mount Persistent Volumes - -In production, you should mount persistent local directories for configuration and data to ensure: - -- Data durability -- Easier backups and recovery -- Full control over storage location and permissions - -Update your `.env` file with custom paths: - -```env -OC_CONFIG_DIR=/your/local/path/opencloud/config -OC_DATA_DIR=/your/local/path/opencloud/data -``` - -:::tip Folder Permissions - -Ensure these folders exist and are owned by user and group 1000:1000, which the Docker containers use by default: - -```bash -sudo mkdir -p /your/local/path/opencloud/{config,data} -sudo chown -R 1000:1000 /your/local/path/opencloud -``` - -::: - -If these variables are left unset, Docker will use internal volumes, which do not persist if the containers are removed — not recommended for real-world use. - -:::caution Security Warning - -The user with UID 1000 on your host system will have full access to these mounted directories. This means that any local user account with this ID can read, modify, or delete OpenCloud config and data files. - -This can pose a security risk in shared or multi-user environments. Make sure to implement proper user and permission management and consider isolating access to these directories. - -::: - -#### Use production release container - -To avoid accidentally updating to a version with breaking changes, you should specify the production container version to be used in your `.env` file: - -```env -OC_DOCKER_IMAGE=opencloudeu/opencloud -OC_DOCKER_TAG=2 -``` +Save the file and exit the editor. ## Start OpenCloud @@ -193,82 +147,27 @@ docker compose up -d This will start all required services in the background. -## Verify SSL Certification - -In your web browser, visit: - -```bash -https://cloud.YOUR.DOMAIN -``` - -You should see a security warning because the staging certificate is not fully trusted. -Same should appear with the other domains you are using. +## Verify Your Deployment -Example with Chrome browser: +After starting OpenCloud, verify that services are running and SSL certificates were issued: -Certificate Details +1. Check the [TLS/SSL certificates are valid](./verify-tls-certificates.md) +2. Log in to OpenCloud: `https://cloud.YOUR.DOMAIN` + - Username: `admin` + - Password: (the password you set in `.env`) -- Check the certificate details to confirm it’s from Let's Encrypt Staging. +## Next Steps - Certificate Details - Certificate Details - -## Apply a Real SSL Certificate - -Once the staging certificate works, switch to a production certificate. - -### Stop Docker Compose - -```bash -docker compose down -``` - -### Remove old staging certificates - -```bash -rm -r certs -``` - -(If you changed volume names, adjust accordingly.) - -### Disable staging mode in `.env` - -```bash -nano .env -``` - -Comment the staging server: - -```bash -# TRAEFIK_ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory -``` - -### Restart OpenCloud with a real SSL certificate - -```bash -docker compose up -d -``` - -✅ Now, visiting `https://cloud.YOUR.DOMAIN` should show a secure connection with a valid SSL certificate. - -Certificate Details - -## Log into OpenCloud - -Open a browser and visit: - -```bash -https://cloud.YOUR.DOMAIN -``` - -Login with: - -Username: `admin` - -Password: (your password) - -Admin general +- **[Verify TLS Certificates](./verify-tls-certificates.md)** – Validate staging certificates and switch to production +- **[Production Setup Considerations](./production-considerations.md)** – Persistent storage, backups, and production best practices +- **[Configure Keycloak](./keycloak-deployment.md)** (optional) – Add Keycloak for enterprise identity management +- **[Configure Authentication](../../../configuration/authentication-and-user-management/)** – User management and identity provider integration ## Troubleshooting -If you encounter any issues, check the [Common Issues & Help](../../../resources/common-issues) +If you encounter issues: + +1. Check Docker logs: `docker compose logs` +2. Verify domain DNS records point to your server +3. Ensure firewall allows HTTP (80) and HTTPS (443) +4. See [Common Issues & Help](../../../resources/common-issues) diff --git a/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/docker-external-proxy.md b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/docker-external-proxy.md index 89750a69..54783ad9 100644 --- a/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/docker-external-proxy.md +++ b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/docker-external-proxy.md @@ -10,17 +10,6 @@ draft: false This guide walks you through setting up OpenCloud behind an external Nginx reverse proxy with Let's Encrypt certificates using `certbot certonly --webroot`. -:::info Traefik as External Proxy -When using Traefik as an external reverse proxy, the following option must be added to the Collabora configuration: - -`--o:hexify_embedded_urls=true` - -This option needs to be included in the Collabora YAML configuration (for example in `collabora.yaml`, Docker Compose, or Helm values). -Without it, embedded URLs may not work correctly. - -See also [Collabora issue](https://github.com/CollaboraOnline/online/issues/13887) -::: - ## Requirements - A public server with a static IP @@ -269,6 +258,10 @@ server { } ``` +:::info Version Differences +Starting from nginx 1.25.0, the `http2` directive syntax changed from: `listen 443 ssl http2;` to `listen 443 ssl; http2 on;` +::: + :::note We enabled HTTP/2 and increased keep-alive limits to prevent large syncs from failing and ensure stable client connections, since nginx closes connections after ~1,000 requests by default. ::: diff --git a/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/keycloak.md b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/keycloak.md index f6762b0b..03e40ec4 100644 --- a/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/keycloak.md +++ b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/keycloak.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 id: keycloak title: Keycloak description: 'OpenCloud with Keycloak.' diff --git a/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/production-setup-consideration.md b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/production-setup-consideration.md new file mode 100644 index 00000000..98486e2c --- /dev/null +++ b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/production-setup-consideration.md @@ -0,0 +1,68 @@ +--- +sidebar_position: 3 +id: production-setup-consideration +title: Production Setup Consideration +description: 'OpenCloud Production Setup Consideration' +draft: true +--- + +# Production Setup Consideration + +:::caution Production Setup Recommended +By default, OpenCloud stores configuration and data inside internal Docker volumes. +This works fine for local development or quick evaluations — but is not suitable for production environments. +::: + +## Mount Persistent Volumes + +For production deployments, you should mount persistent local directories for configuration and data. This ensures: + +- Data durability +- Easier backups and recovery +- Full control over storage location and permissions + +### Update your `.env` file with custom paths + +```bash +OC_CONFIG_DIR=/your/local/path/opencloud/config +OC_DATA_DIR=/your/local/path/opencloud/data +``` + +### Set your email for SSL certification + +```bash +TRAEFIK_ACME_MAIL=your@email.com +``` + +:::tip Folder Permissions + +### Ensure these folders exist and are owned by user and group 1000:1000, which the Docker containers use by default + +```bash +sudo mkdir -p /your/local/path/opencloud/{config,data} +sudo chown -R 1000:1000 /your/local/path/opencloud +``` + +::: + +If these variables are not set, Docker will use internal volumes. +These volumes may be removed when containers are deleted, which means your configuration and data may be lost. This setup is therefore not recommended for production use. + +:::caution Security Warning + +The user with UID 1000 on your host system will have full access to these mounted directories. This means that any local user account with this ID can read, modify, or delete OpenCloud config and data files. + +This can pose a security risk in shared or multi-user environments. Make sure to implement proper user and permission management and consider isolating access to these directories. + +::: + +## Use production release container + +To avoid accidentally upgrading to versions that may contain breaking changes, you should explicitly specify the container image and version in your .env file. + +```bash +OC_DOCKER_IMAGE=opencloudeu/opencloud +OC_DOCKER_TAG=2 +``` + +This ensures that your deployment always uses a stable production release instead of automatically pulling newer versions. diff --git a/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/verify-SSL-certification.md b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/verify-SSL-certification.md new file mode 100644 index 00000000..7fa9acde --- /dev/null +++ b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/verify-SSL-certification.md @@ -0,0 +1,101 @@ +--- +sidebar_position: 4 +id: verify-SSL-certification +title: Verify SSL Certification +description: 'Verify SSL Certification in OpenCloud' +draft: true +--- + +# Verify SSL Certification + +## After starting OpenCloud, verify that the SSL certificates were issued correctly + +Open the following URL in your web browser: + +```bash +https://cloud.YOUR.DOMAIN +``` + +Because the setup currently uses Let's Encrypt staging certificates, your browser will show a security warning. This is expected, as staging certificates are not trusted by browsers. + +The same warning may appear for the other domains you configured. + +Example in the Chrome browser: + +Certificate Details + +- Check the certificate details to confirm that the certificate was issued by Let's Encrypt Staging. + + Certificate Details + Certificate Details + +## Apply a Real SSL Certificate + +Once the staging certificate works correctly, you can switch to a production SSL certificate. + +### Stop Docker Compose + +Stop the running containers: + +```bash +docker compose down +``` + +### Remove old staging certificates + +Delete the previously generated staging certificates: + +```bash +rm -r certs +``` + +If you changed volume names or paths, adjust this command accordingly. + +### Disable staging mode in `.env` + +Open the environment file: + +```bash +nano .env +``` + +Comment the staging server: + +```bash +# TRAEFIK_ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory +``` + +### Restart OpenCloud with a real SSL certificate + +Start the containers again: + +```bash +docker compose up -d +``` + +OpenCloud will now request trusted production certificates from Let's Encrypt. + +After a short moment, visiting the following URL should show a secure HTTPS connection: + +Certificate Details + +## Log into OpenCloud + +Open a browser and visit: + +```bash +https://cloud.YOUR.DOMAIN +``` + +Login with: + +Username: `admin` + +Password: (the password you configured in the .env file) + +Admin general + +## Troubleshooting + +If you encounter any issues during the setup process, check the troubleshooting guide: +[Common Issues & Help](../../../resources/common-issues) diff --git a/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/volume-permissions.md b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/volume-permissions.md new file mode 100644 index 00000000..a1a55284 --- /dev/null +++ b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/volume-permissions.md @@ -0,0 +1,245 @@ +--- +sidebar_position: 7 +id: docker-compose-volume-permissions +title: Volume Permissions and UID/GID Management +description: Understanding and managing filesystem permissions for OpenCloud Docker volumes +--- + +# Volume Permissions and UID/GID Management + +This guide explains how to properly configure filesystem permissions for OpenCloud's persistent volumes in Docker Compose deployments. Understanding UID/GID mappings is crucial for production deployments with mounted volumes. + +## Default Container User + +OpenCloud containers run as a non-root user with: + +- **UID (User ID):** 1000 +- **GID (Group ID):** 1000 + +This is the user that reads and writes to all data, configuration, and cache directories within the container. + +## Mount Point Permissions + +When you mount directories from your host system into the container, the container's UID 1000 must have proper read/write access. + +### Correct Setup + +```bash +# Create directories +sudo mkdir -p /your/local/path/opencloud/{config,data} + +# Set ownership to UID/GID 1000:1000 +sudo chown -R 1000:1000 /your/local/path/opencloud + +# Set appropriate permissions (owner can read/write/execute, others cannot) +sudo chmod -R 0700 /your/local/path/opencloud +``` + +Directory structure should look like: + +```bash +/your/local/path/opencloud/ +├── config/ (UID 1000 owner, mode 0700) +│ ├── opencloud.config.php +│ ├── redis/ +│ └── nginx/ +└── data/ (UID 1000 owner, mode 0700) + ├── database/ + ├── files/ + └── objectstorage/ +``` + +### Verifying permissions + +Check that directories are owned by 1000:1000: + +```bash +ls -ln /your/local/path/opencloud/ +# Example output: +# drwx------ 5 1000 1000 4096 Jan 15 10:30 config +# drwx------ 8 1000 1000 4096 Jan 16 14:22 data +``` + +## Understanding UID Mapping + +### Host user with UID 1000 + +If your host system has a user with UID 1000 (e.g., the first non-root user created): + +```bash +id myuser +# Output: uid=1000(myuser) gid=1000(myuser) groups=1000(myuser) +``` + +That user can directly access the mounted directories: + +```bash +ls /your/local/path/opencloud/config +cd /your/local/path/opencloud/data +``` + +This is the **most common case** and requires minimal configuration. + +### UID mismatch scenarios + +**Problem:** Your host system's UID 1000 is assigned to a different user (or doesn't exist). + +```bash +cat /etc/passwd | grep 1000 +# (empty or shows different user) +``` + +**Solution:** Create a dedicated service user or adjust permissions: + +```bash +# Option 1: Create a dedicated user for OpenCloud +sudo useradd -u 1000 -m -s /usr/sbin/nologin opencloud + +# Then change ownership +sudo chown -R opencloud:opencloud /your/local/path/opencloud + +# Option 2: Use numeric IDs in chown +sudo chown -R 1000:1000 /your/local/path/opencloud +``` + +## Permission Modes Explained + +### Recommended: 0700 (rwx------) + +```bash +sudo chmod -R 0700 /your/local/path/opencloud +``` + +- Owner (UID 1000): read, write, execute +- Group members: no access +- Others: no access + +**Use case:** Maximum security; only the container user can access. + +### More permissive: 0750 (rwxr-x---) + +```bash +sudo chmod -R 0750 /your/local/path/opencloud +``` + +- Owner: read, write, execute +- Group members: read, execute +- Others: no access + +**Use case:** Allows other group members to read (useful for backups, monitoring). + +### Caution: 0755 (rwxr-xr-x) + +```bash +sudo chmod -R 0755 /your/local/path/opencloud +``` + +- Everyone can read and list directories + +**Warning:** Not recommended for data directories containing sensitive information. + +## Bind Mounts vs Named Volumes + +### Bind Mounts (Recommended for persistent data) + +```bash +# In .env or docker-compose override +OC_CONFIG_DIR=/your/local/path/opencloud/config +OC_DATA_DIR=/your/local/path/opencloud/data +``` + +**Advantages:** + +- Full control over permissions and ownership +- Easy to backup +- Direct host filesystem access + +**You must manually manage permissions.** + +### Named Volumes (Docker-managed) + +If not set, Docker creates automatic volumes: + +```bash +# Volumes are stored in /var/lib/docker/volumes/ +docker volume ls +``` + +**Advantages:** + +- Docker manages permissions automatically +- Docker handles backup/restore + +**Disadvantages:** + +- Harder to access directly +- Less control over ownership +- Not recommended for production + +## Troubleshooting Permission Issues + +### "Permission denied" errors in container + +If OpenCloud container can't read/write: + +```bash +# Check container can see files +docker compose exec opencloud ls -la /var/opencloud/config + +# If permission denied, check host ownership +ls -ln /your/local/path/opencloud/config + +# Fix: Change ownership +sudo chown -R 1000:1000 /your/local/path/opencloud +``` + +### Cannot write after mounting + +```bash +# Error: "Read-only file system" +# Solution: Ensure directory is writable +sudo chmod u+w /your/local/path/opencloud/{config,data} +``` + +### Backup/restore permission issues + +When restoring from backup: + +```bash +# After extracting backup, fix permissions +sudo chown -R 1000:1000 /your/local/path/opencloud +sudo chmod -R 0700 /your/local/path/opencloud +``` + +## Security Considerations + +:::caution +UID 1000 on your host system will have **full read/write access** to OpenCloud data. + +In multi-user or shared hosting environments: + +1. Isolate the host user (e.g., dedicated service account) +2. Restrict SSH/shell access appropriately +3. Use additional filesystem-level security (SELinux, AppArmor) +4. Regularly audit file access + + ::: + +## Environment Variables for Persistence + +```bash +# In .env file +OC_CONFIG_DIR=/your/local/path/opencloud/config +OC_DATA_DIR=/your/local/path/opencloud/data +OC_LOG_DIR=/your/local/path/opencloud/logs + +# Ensure these directories exist with correct permissions +``` + +If these variables are not set, Docker will use unnamed volumes that persist only as long as containers are not removed. + +## See Also + +- **[Production Considerations](./production-considerations.md)** – Volume mounting setup +- **[Docker documentation on volumes](https://docs.docker.com/storage/volumes/)** +- **[Linux permission quick reference](https://en.wikipedia.org/wiki/File-system_permissions)** From 72f1516e69818ce798a64e0be5457ba7dcf68cd0 Mon Sep 17 00:00:00 2001 From: Anja Barz Date: Mon, 23 Mar 2026 14:05:35 +0100 Subject: [PATCH 4/4] rewerite again the docker-compose section for better structure and understanding --- .../docker-compose/docker-compose-base.md | 146 ++++++++++-- .../docker-compose/docker-external-proxy.md | 20 +- .../container/docker-compose/index.md | 43 ++-- .../docker-compose/keycloak-deployment.md | 16 +- .../production-considerations.md | 48 ++-- .../docker-compose/verify-tls-certificates.md | 171 ------------- .../docker-compose/volume-permissions.md | 224 ++++-------------- .../docker-compose/docker-compose-base.md | 10 +- .../docker-compose/volume-permissions.md | 32 +-- 9 files changed, 237 insertions(+), 473 deletions(-) delete mode 100644 docs/admin/getting-started/container/docker-compose/verify-tls-certificates.md diff --git a/docs/admin/getting-started/container/docker-compose/docker-compose-base.md b/docs/admin/getting-started/container/docker-compose/docker-compose-base.md index dfda07f4..48c6fe46 100644 --- a/docs/admin/getting-started/container/docker-compose/docker-compose-base.md +++ b/docs/admin/getting-started/container/docker-compose/docker-compose-base.md @@ -1,7 +1,7 @@ --- sidebar_position: 1 id: docker-compose-base -title: Docker Compose Base +title: Default Setup with Traefik description: Full-blown featureset including web office. draft: false --- @@ -10,12 +10,12 @@ draft: false Install an internet-facing OpenCloud instance with automatic SSL certificates using Docker Compose's integrated Traefik reverse proxy. -This is the **recommended deployment path** for most new OpenCloud installations. Traefik automatically manages Let's Encrypt SSL certificates, eliminating the need to manage a separate reverse proxy. +This is the recommended deployment path for most new OpenCloud installations. Traefik automatically manages Let's Encrypt SSL certificates, eliminating the need to manage a separate reverse proxy. This installation guide is written for Ubuntu and Debian systems. The software can also be installed on other Linux distributions, but commands and package managers may differ. :::note Not using Traefik? -If you already have an external reverse proxy (Nginx, HAProxy, etc.) or prefer to manage it separately, see [Deploy Behind External Proxy](./external-proxy.md) instead. +If you already have an external reverse proxy (Nginx, HAProxy, etc.) or prefer to manage it separately, see [Deploy Behind External Proxy](./docker-external-proxy.md) instead. ::: ## Prerequisites @@ -127,14 +127,22 @@ TRAEFIK_ACME_MAIL=your@email.com TRAEFIK_ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory ``` -### Set your deployment options +### Set the deployment option -Example configuration without Collabora: +Set the `COMPOSE_FILE` variable based on the components you want to deploy. + +For an OpenCloud deployment without Collabora, use: ```bash COMPOSE_FILE=docker-compose.yml:traefik/opencloud.yml ``` +To deploy OpenCloud with Collabora, use: + +```bash +COMPOSE_FILE=docker-compose.yml:weboffice/collabora.yml:traefik/opencloud.yml:traefik/collabora.yml:radicale/radicale.yml +``` + Save the file and exit the editor. ## Start OpenCloud @@ -147,21 +155,127 @@ docker compose up -d This will start all required services in the background. -## Verify Your Deployment +## Verify TLS Certificates + +After starting OpenCloud, verify that SSL certificates were issued correctly and switch from staging to production certificates when ready. + +### Verify Staging Certificates + +By default, the setup uses Let's Encrypt staging certificates for testing. These are not trusted by browsers but prove that the DNS and certificate generation workflow is correct. + +Open the following URL: + +```bash +https://cloud.YOUR.DOMAIN +``` + +Because the setup currently uses Let's Encrypt staging certificates, your browser will show a security warning. This is expected and normal for the staging environment. + +The same warning may appear for the other configured domains. + +### Example in Chrome + +Click on the lock icon to view certificate details: + +Certificate Details + +Expand the certificate information to confirm it was issued by "Let's Encrypt Staging": + +Certificate Details + +Certificate Details Subordinate CA + +:::success Staging Certificate Success +If you see "Let's Encrypt Staging" as the issuer, the certificate generation is working correctly. You can now safely switch to production certificates. +::: + +## Switch to Production Certificates + +Once the staging certificate works correctly, you can switch to production SSL certificates from Let's Encrypt. + +### Stop Docker Compose + +```bash +docker compose down +``` + +### Remove old staging certificates + +Delete the previously generated staging certificates: + +```bash +rm -r certs +``` + +:::warning +If you changed volume names or paths in your `.env` file, adjust this command to match your certificate directory. +::: -After starting OpenCloud, verify that services are running and SSL certificates were issued: +### Disable staging mode in `.env` -1. Check the [TLS/SSL certificates are valid](./verify-tls-certificates.md) -2. Log in to OpenCloud: `https://cloud.YOUR.DOMAIN` +Open the environment file: + +```bash +nano .env +``` + +Comment out or remove the staging server line: + +```bash +# TRAEFIK_ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory +``` + +Save the file. + +### Restart OpenCloud with production certificates + +Start the containers again: + +```bash +docker compose up -d +``` + +Traefik will now request trusted production certificates from Let's Encrypt. + +### Wait for certificate generation + +Certificate generation may take a few moments. Check the logs: + +```bash +docker compose logs traefik +``` + +Look for messages indicating successful certificate generation. + +### Verify production certificates + +After a short moment, visiting your domain should show a secure HTTPS connection: + +Secure Connection + +The lock icon should show "Secure" (green lock) with "Let's Encrypt Authority X3" or similar as the issuer. + +## Log into OpenCloud + +Once certificates are verified: + +1. Open your domain in a browser: + +```bash +https://cloud.YOUR.DOMAIN +``` + +2. Log in with your admin credentials: - Username: `admin` - - Password: (the password you set in `.env`) + - Password: (the password you configured in the `.env` file) + +OpenCloud Login -## Next Steps +## Further Configuration -- **[Verify TLS Certificates](./verify-tls-certificates.md)** – Validate staging certificates and switch to production -- **[Production Setup Considerations](./production-considerations.md)** – Persistent storage, backups, and production best practices -- **[Configure Keycloak](./keycloak-deployment.md)** (optional) – Add Keycloak for enterprise identity management -- **[Configure Authentication](../../../configuration/authentication-and-user-management/)** – User management and identity provider integration +- [Production Setup Considerations](./production-considerations.md) – Persistent storage, backups, and production best practices +- [Configure Keycloak](./keycloak-deployment.md) (optional) – Add Keycloak for enterprise identity management +- [Configure Authentication](../../../configuration/authentication-and-user-management/) – User management and identity provider integration ## Troubleshooting @@ -170,4 +284,4 @@ If you encounter issues: 1. Check Docker logs: `docker compose logs` 2. Verify domain DNS records point to your server 3. Ensure firewall allows HTTP (80) and HTTPS (443) -4. See [Common Issues & Help](../../../resources/common-issues) +4. See [Common Issues & Help](../../../resources/common-issues.md) diff --git a/docs/admin/getting-started/container/docker-compose/docker-external-proxy.md b/docs/admin/getting-started/container/docker-compose/docker-external-proxy.md index 314df874..598b5463 100644 --- a/docs/admin/getting-started/container/docker-compose/docker-external-proxy.md +++ b/docs/admin/getting-started/container/docker-compose/docker-external-proxy.md @@ -11,7 +11,7 @@ draft: false This guide walks you through setting up OpenCloud behind an external Nginx reverse proxy with Let's Encrypt certificates using `certbot certonly --webroot`. :::note Using Traefik Instead? -If you don't have an existing reverse proxy or prefer to let Traefik manage certificates automatically, see [Docker Compose with Integrated Traefik](./integrated-traefik.md) instead. +If you don't have an existing reverse proxy or prefer to let Traefik manage certificates automatically, see [Docker Compose with Integrated Traefik](./docker-compose-base.md) instead. ::: ## Requirements @@ -38,20 +38,6 @@ ssh root@YOUR.SERVER.IP Update your system and install Docker. -First, perform an update and upgrade: - -```bash -apt update && apt upgrade -y -``` - -Install Docker following the [official Docker guide](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository) - -Once Docker is installed, enable and start the service: - -```bash -systemctl enable docker && systemctl start docker -``` - ## Install Nginx & Certbot Now install Nginx & Certbot @@ -149,12 +135,12 @@ Start the docker compose setup docker compose up -d ``` -## Next Steps +## Further Configuration For production deployments, review [Production Considerations](./production-considerations.md) for: - Persistent volumes and data recovery -- Image version pinning +- Using the appropriate stable branch - Permission and ownership best practices ## Set Up the Final Nginx Reverse Proxy diff --git a/docs/admin/getting-started/container/docker-compose/index.md b/docs/admin/getting-started/container/docker-compose/index.md index 6e02c730..ae32f49c 100644 --- a/docs/admin/getting-started/container/docker-compose/index.md +++ b/docs/admin/getting-started/container/docker-compose/index.md @@ -11,47 +11,36 @@ This section guides you through deploying OpenCloud using Docker Compose. We sup ## Choose Your Deployment Path -### 1. **Integrated Traefik** (Recommended for most users) +### 1. Integrated Traefik (Recommended for most users) Use the built-in Traefik reverse proxy and automatic Let's Encrypt SSL certificates. This is the standard, recommended path for new deployments. -**Best for:** +Best for: - Standalone servers - No existing reverse proxy infrastructure - Simple, self-contained setup -[Get Started with Integrated Traefik →](./integrated-traefik.md) +[Get Started with Integrated Traefik →](./docker-compose-base.md) -### 2. **Behind External Proxy** (For existing infrastructure) +### 2. Behind External Proxy -Deploy OpenCloud behind your own Nginx, HAProxy, or other reverse proxy. Choose this if you already have a reverse proxy in place or prefer to manage it separately. +Use this setup if you want to run OpenCloud behind your own reverse proxy instead of the integrated Traefik setup. -**Best for:** +The guide includes the required OpenCloud settings and an example Nginx configuration. -- Multi-service environments -- Existing reverse proxy infrastructure -- Complex networking requirements +Best for: -[Deploy Behind External Proxy →](./external-proxy.md) +- Existing reverse proxy environments +- Custom TLS handling +- Separate proxy management -## Next Steps +[Deploy Behind External Proxy →](./docker-external-proxy.md) -After choosing and completing your deployment: - -- **[Production Setup Considerations](./production-considerations.md)** – Persistent storage, backups, image versions -- **[Verify TLS Certificates](./verify-tls-certificates.md)** – Validate your SSL setup -- **[Configure Authentication](../../../configuration/authentication-and-user-management/)** – Users, authentication, and optional Keycloak integration - -## Project Structure +## Further Configuration -Both deployment paths use the same underlying composition of services: - -- OpenCloud server -- Collabora Online Editor (optional) -- WOPI Server -- Database -- Object Storage (MinIO) -- Optional: Traefik (integrated path) or your external proxy (external path) +After choosing and completing your deployment: -Choose the path that best matches your infrastructure and requirements. +- [Production Setup Considerations](./production-considerations.md) – Persistent storage, backups, image versions +- [Verify TLS Certificates](./docker-compose-base.md#verify-tls-certificates) – Validate your SSL setup +- [Configure Authentication](../../../configuration/authentication-and-user-management/) – Users, authentication, and optional Keycloak integration diff --git a/docs/admin/getting-started/container/docker-compose/keycloak-deployment.md b/docs/admin/getting-started/container/docker-compose/keycloak-deployment.md index 583cc368..a5af53dc 100644 --- a/docs/admin/getting-started/container/docker-compose/keycloak-deployment.md +++ b/docs/admin/getting-started/container/docker-compose/keycloak-deployment.md @@ -1,7 +1,7 @@ --- sidebar_position: 6 id: docker-compose-keycloak-deployment -title: Enable Keycloak Integration +title: Keycloak Integration description: Add Keycloak identity management to your Docker Compose OpenCloud deployment draft: false --- @@ -11,7 +11,7 @@ draft: false This guide explains how to enable Keycloak as an identity provider (IdP) for your Docker Compose OpenCloud deployment. This provides enterprise-grade user and access management. :::note -This page covers **deployment setup only**. For detailed Keycloak configuration, user management, and integration patterns, see the [Keycloak Configuration Guide](../../../configuration/authentication-and-user-management/keycloak.md). +This page covers deployment setup only. For detailed Keycloak configuration, user management, and integration patterns, see the [Keycloak Configuration Guide](../../../configuration/authentication-and-user-management/keycloak.md). ::: ## Prerequisites @@ -28,7 +28,7 @@ cd opencloud-compose nano .env ``` -Add or uncomment the following lines to enable **Keycloak with integrated LDAP**: +Add or uncomment the following lines to enable Keycloak with integrated LDAP: ```bash # Enable Keycloak + LDAP services @@ -84,8 +84,8 @@ https://keycloak.YOUR.DOMAIN Log in with the credentials you set in `.env`: -- **Username:** `admin` (or your `KEYCLOAK_ADMIN` value) -- **Password:** Your `KEYCLOAK_ADMIN_PASSWORD` +- Username: `admin` (or your `KEYCLOAK_ADMIN` value) +- Password: Your `KEYCLOAK_ADMIN_PASSWORD` ## Next Steps @@ -146,6 +146,6 @@ If using `idm/ldap-keycloak.yml`: ## See Also -- **[Full Keycloak Integration Guide](../../../configuration/authentication-and-user-management/keycloak.md)** – Configuration, modes, and advanced setup -- **[User Management with Keycloak](../../../configuration/authentication-and-user-management/keycloak-user.md)** – Creating users and managing roles -- **[Production Considerations](./production-considerations.md)** – Backup and production best practices +- [Full Keycloak Integration Guide](../../../configuration/authentication-and-user-management/keycloak.md) – Configuration, modes, and advanced setup +- [User Management with Keycloak](../../../configuration/authentication-and-user-management/keycloak-user.md) – Creating users and managing roles +- [Production Considerations](./production-considerations.md) – Backup and production best practices diff --git a/docs/admin/getting-started/container/docker-compose/production-considerations.md b/docs/admin/getting-started/container/docker-compose/production-considerations.md index 6fe8d6e2..efe7f30a 100644 --- a/docs/admin/getting-started/container/docker-compose/production-considerations.md +++ b/docs/admin/getting-started/container/docker-compose/production-considerations.md @@ -18,9 +18,9 @@ This works fine for local development or quick evaluations — but is not suitab For production deployments, you should mount persistent local directories for configuration and data. This ensures: -- **Data durability** – Configuration and data persist across container restarts -- **Easier backups and recovery** – Access files directly from the host -- **Full control over storage location and permissions** – Meet organizational compliance requirements +- Data durability – Configuration and data persist across container restarts +- Easier backups and recovery – Access files directly from the host +- Full control over storage location and permissions – Meet organizational compliance requirements ### Update your `.env` file with custom paths @@ -61,44 +61,24 @@ For more details on volume permissions, see [Volume Permissions and UID/GID Mana ::: -## Pin Container Images for Stability +## Use the appropriate repository branch -To avoid accidentally upgrading to versions that may contain breaking changes, explicitly specify the container image version in your `.env` file: +By default, the `main` branch of the `opencloud-compose` repository tracks the rolling release. + +For production deployments, use the current `stable-*` branch instead, for example: ```bash -OC_DOCKER_IMAGE=opencloudeu/opencloud -OC_DOCKER_TAG=2 +git checkout stable-4.0 ``` -**Recommended approach:** - -- Use major version tags (e.g., `2`, `3`) for stable production releases -- Test minor/patch updates in a staging environment before production -- Avoid using `latest` tag in production, as it may introduce unexpected changes - -This ensures your deployment always uses a stable, tested release instead of automatically pulling newer versions. +Stable branch names change over time as new stable releases become available. Moving from one stable-\* branch to another is an update and should be handled accordingly. ## Backup and Recovery Strategy -With persistent volumes in place, implement a backup strategy: - -1. **Regular snapshots** of `OC_CONFIG_DIR` and `OC_DATA_DIR` -2. **Database backups** (typically in `OC_DATA_DIR`) -3. **Off-site storage** for disaster recovery -4. **Test recovery procedures** regularly - -Refer to your system administration practices for backup tools (rsync, tar, Restic, etc.). - -## Environment and SSL Certificates - -Once your staging setup is working: - -1. Switch to **Let's Encrypt production certificates** – See [Verify TLS Certificates](./verify-tls-certificates.md#apply-a-real-ssl-certificate) -2. Update **security headers and policies** in your reverse proxy -3. Enable **HSTS (HTTP Strict Transport Security)** for production domains +With persistent volumes in place, you should implement a backup and recovery strategy for your OpenCloud deployment: -## Next Steps +- Regular backups of `OC_CONFIG_DIR` and `OC_DATA_DIR` +- Off-site or remote storage for disaster recovery +- Regular verification and testing of restore procedures -- **[Verify TLS Certificates](./verify-tls-certificates.md)** – Switch from staging to production certificates -- **[Volume Permissions Guide](./volume-permissions.md)** – Detailed UID/GID and permission management -- **[Maintenance & Monitoring](../../maintenance/)** – Logging and system health checks +For detailed backup guidance, see the [Backup documentation](../../../maintenance/backup.md). diff --git a/docs/admin/getting-started/container/docker-compose/verify-tls-certificates.md b/docs/admin/getting-started/container/docker-compose/verify-tls-certificates.md deleted file mode 100644 index a992dd48..00000000 --- a/docs/admin/getting-started/container/docker-compose/verify-tls-certificates.md +++ /dev/null @@ -1,171 +0,0 @@ ---- -sidebar_position: 5 -id: docker-compose-verify-tls -title: Verify TLS/SSL Certificates -description: Validate SSL certificates and migrate from Let's Encrypt staging to production ---- - -# Verify TLS and SSL Certificates - -After starting OpenCloud with Docker Compose and Traefik, verify that SSL certificates were issued correctly and switch from staging to production certificates when ready. - -:::note -This guide applies to the [integrated Traefik deployment](./integrated-traefik.md). For external proxy setups, see [Behind External Proxy](./external-proxy.md). -::: - -## Verify Staging Certificates - -By default, the setup uses **Let's Encrypt staging certificates** for testing. These are not trusted by browsers but prove that the DNS and certificate generation workflow is correct. - -### Open your domain in a web browser - -Open the following URL: - -```bash -https://cloud.YOUR.DOMAIN -``` - -Because the setup currently uses Let's Encrypt staging certificates, your browser will show a security warning. **This is expected and normal for the staging environment.** - -The same warning may appear for the other configured domains. - -### Example in Chrome - -Click on the lock icon to view certificate details: - -Certificate Details - -Expand the certificate information to confirm it was issued by "Let's Encrypt Staging": - -Certificate Details - -Certificate Details Subordinate CA - -:::success Staging Certificate Success -If you see "Let's Encrypt Staging" as the issuer, the certificate generation is working correctly. You can now safely switch to production certificates. -::: - -## Apply a Real SSL Certificate - -Once the staging certificate works correctly, you can switch to production SSL certificates from Let's Encrypt. - -### Stop Docker Compose - -```bash -docker compose down -``` - -### Remove old staging certificates - -Delete the previously generated staging certificates: - -```bash -rm -r certs -``` - -:::warning -If you changed volume names or paths in your `.env` file, adjust this command to match your certificate directory. -::: - -### Disable staging mode in `.env` - -Open the environment file: - -```bash -nano .env -``` - -Comment out or remove the staging server line: - -```bash -# TRAEFIK_ACME_CASERVER=https://acme-staging-v02.api.letsencrypt.org/directory -``` - -Save the file. - -### Restart OpenCloud with production certificates - -Start the containers again: - -```bash -docker compose up -d -``` - -Traefik will now request trusted production certificates from Let's Encrypt. - -### Wait for certificate generation - -Certificate generation may take a few moments. Check the logs: - -```bash -docker compose logs traefik -``` - -Look for messages indicating successful certificate generation. - -### Verify production certificates - -After a short moment, visiting your domain should show a secure HTTPS connection: - -Secure Connection - -The lock icon should show "Secure" (green lock) with "Let's Encrypt Authority X3" or similar as the issuer. - -## Log into OpenCloud - -Once certificates are verified: - -1. Open your domain in a browser: - -```bash -https://cloud.YOUR.DOMAIN -``` - -2. Log in with your admin credentials: - - **Username:** `admin` - - **Password:** (the password you configured in the `.env` file) - -OpenCloud Login - -## Troubleshooting - -### Certificate generation fails - -**Check Traefik logs:** - -```bash -docker compose logs traefik -``` - -Look for error messages about ACME challenges. - -### DNS issues - -Ensure your domain correctly points to your server: - -```bash -nslookup cloud.YOUR.DOMAIN -``` - -The result should match your server's IP address. - -### Port 80/443 not accessible - -Verify firewall rules allow: - -- HTTP (port 80) – Required for ACME challenge -- HTTPS (port 443) – Required for OpenCloud access - -### Certificate not updating - -If Traefik fails to renew certificates: - -1. Check available disk space -2. Verify ACME email is correct in `.env` -3. Review Traefik configuration in your Docker Compose setup - -## Next Steps - -- **[Production Considerations](./production-considerations.md)** – Persistent storage and production best practices -- **[Configure Keycloak](./keycloak-deployment.md)** (optional) – Add enterprise identity management -- **[Maintenance & Monitoring](../../maintenance/)** – System health and logging diff --git a/docs/admin/getting-started/container/docker-compose/volume-permissions.md b/docs/admin/getting-started/container/docker-compose/volume-permissions.md index a1a55284..25f24056 100644 --- a/docs/admin/getting-started/container/docker-compose/volume-permissions.md +++ b/docs/admin/getting-started/container/docker-compose/volume-permissions.md @@ -1,245 +1,111 @@ --- sidebar_position: 7 id: docker-compose-volume-permissions -title: Volume Permissions and UID/GID Management -description: Understanding and managing filesystem permissions for OpenCloud Docker volumes +title: Volume Permissions +description: Configure filesystem permissions for OpenCloud Docker volumes --- -# Volume Permissions and UID/GID Management +# Volume Permissions -This guide explains how to properly configure filesystem permissions for OpenCloud's persistent volumes in Docker Compose deployments. Understanding UID/GID mappings is crucial for production deployments with mounted volumes. +OpenCloud runs as a non-root user inside the container and requires read and write access to the mounted configuration and data directories. -## Default Container User +When using bind mounts, ensure that the directories referenced by `OC_CONFIG_DIR` and `OC_DATA_DIR` are writable by the container user. -OpenCloud containers run as a non-root user with: +## Recommended permissions -- **UID (User ID):** 1000 -- **GID (Group ID):** 1000 - -This is the user that reads and writes to all data, configuration, and cache directories within the container. - -## Mount Point Permissions - -When you mount directories from your host system into the container, the container's UID 1000 must have proper read/write access. - -### Correct Setup +Create the directories on the host and assign them to UID and GID `1000`: ```bash -# Create directories sudo mkdir -p /your/local/path/opencloud/{config,data} - -# Set ownership to UID/GID 1000:1000 sudo chown -R 1000:1000 /your/local/path/opencloud - -# Set appropriate permissions (owner can read/write/execute, others cannot) sudo chmod -R 0700 /your/local/path/opencloud ``` -Directory structure should look like: - -```bash -/your/local/path/opencloud/ -├── config/ (UID 1000 owner, mode 0700) -│ ├── opencloud.config.php -│ ├── redis/ -│ └── nginx/ -└── data/ (UID 1000 owner, mode 0700) - ├── database/ - ├── files/ - └── objectstorage/ -``` - -### Verifying permissions - -Check that directories are owned by 1000:1000: +To verify the ownership on the host, run: ```bash ls -ln /your/local/path/opencloud/ -# Example output: -# drwx------ 5 1000 1000 4096 Jan 15 10:30 config -# drwx------ 8 1000 1000 4096 Jan 16 14:22 data ``` -## Understanding UID Mapping +## Rootless Docker and UID Mapping -### Host user with UID 1000 +When Docker runs in rootless mode, bind-mounted directories do not always use the same ownership mapping you see in a regular Docker setup. -If your host system has a user with UID 1000 (e.g., the first non-root user created): +The OpenCloud container still runs as UID and GID `1000` inside the container, but rootless Docker maps that identity into the subordinate UID and GID range configured for your host user. As a result, a host directory owned by `1000:1000` may not be writable inside the container. -```bash -id myuser -# Output: uid=1000(myuser) gid=1000(myuser) groups=1000(myuser) -``` +### Check subordinate IDs -That user can directly access the mounted directories: +You can inspect the subordinate UID and GID ranges on the host with: ```bash -ls /your/local/path/opencloud/config -cd /your/local/path/opencloud/data +grep "^$(whoami):" /etc/subuid +grep "^$(whoami):" /etc/subgid ``` -This is the **most common case** and requires minimal configuration. - -### UID mismatch scenarios - -**Problem:** Your host system's UID 1000 is assigned to a different user (or doesn't exist). +If the output looks like this: -```bash -cat /etc/passwd | grep 1000 -# (empty or shows different user) +```text +youruser:100000:65536 +youruser:100000:65536 ``` -**Solution:** Create a dedicated service user or adjust permissions: - -```bash -# Option 1: Create a dedicated user for OpenCloud -sudo useradd -u 1000 -m -s /usr/sbin/nologin opencloud - -# Then change ownership -sudo chown -R opencloud:opencloud /your/local/path/opencloud +then container UID `1000` maps to host UID `101000`. -# Option 2: Use numeric IDs in chown -sudo chown -R 1000:1000 /your/local/path/opencloud -``` +### Adjust ownership -## Permission Modes Explained - -### Recommended: 0700 (rwx------) +In that case, set the bind-mounted directories to the mapped host UID and GID: ```bash +sudo chown -R 101000:101000 /your/local/path/opencloud sudo chmod -R 0700 /your/local/path/opencloud ``` -- Owner (UID 1000): read, write, execute -- Group members: no access -- Others: no access - -**Use case:** Maximum security; only the container user can access. +### Verify access inside the container -### More permissive: 0750 (rwxr-x---) +Do not rely only on host-side ownership values in rootless mode. Verify that the OpenCloud container can actually read and write the mounted directories: ```bash -sudo chmod -R 0750 /your/local/path/opencloud +docker compose exec opencloud sh +ls -la /etc/opencloud +ls -la /var/lib/opencloud +touch /var/lib/opencloud/.write-test ``` -- Owner: read, write, execute -- Group members: read, execute -- Others: no access +If those commands succeed, the permissions are configured correctly. -**Use case:** Allows other group members to read (useful for backups, monitoring). +### Prefer a simpler setup -### Caution: 0755 (rwxr-xr-x) +If you do not want to manage mapped host UID and GID values manually, consider using Docker named volumes instead of bind mounts for rootless setups. -```bash -sudo chmod -R 0755 /your/local/path/opencloud -``` - -- Everyone can read and list directories - -**Warning:** Not recommended for data directories containing sensitive information. +## Troubleshooting -## Bind Mounts vs Named Volumes +If OpenCloud reports permission errors, verify the mounted directories from both the host and the container. -### Bind Mounts (Recommended for persistent data) +### Check on the host ```bash -# In .env or docker-compose override -OC_CONFIG_DIR=/your/local/path/opencloud/config -OC_DATA_DIR=/your/local/path/opencloud/data -``` - -**Advantages:** - -- Full control over permissions and ownership -- Easy to backup -- Direct host filesystem access - -**You must manually manage permissions.** - -### Named Volumes (Docker-managed) - -If not set, Docker creates automatic volumes: - -```bash -# Volumes are stored in /var/lib/docker/volumes/ -docker volume ls -``` - -**Advantages:** - -- Docker manages permissions automatically -- Docker handles backup/restore - -**Disadvantages:** - -- Harder to access directly -- Less control over ownership -- Not recommended for production - -## Troubleshooting Permission Issues - -### "Permission denied" errors in container - -If OpenCloud container can't read/write: - -```bash -# Check container can see files -docker compose exec opencloud ls -la /var/opencloud/config - -# If permission denied, check host ownership -ls -ln /your/local/path/opencloud/config - -# Fix: Change ownership -sudo chown -R 1000:1000 /your/local/path/opencloud +ls -ln /your/local/path/opencloud/ ``` -### Cannot write after mounting +### Check inside the container ```bash -# Error: "Read-only file system" -# Solution: Ensure directory is writable -sudo chmod u+w /your/local/path/opencloud/{config,data} +docker compose exec opencloud ls -la /etc/opencloud +docker compose exec opencloud ls -la /var/lib/opencloud ``` -### Backup/restore permission issues - -When restoring from backup: +If needed, re-apply ownership and permissions on the host: ```bash -# After extracting backup, fix permissions sudo chown -R 1000:1000 /your/local/path/opencloud sudo chmod -R 0700 /your/local/path/opencloud ``` -## Security Considerations - -:::caution -UID 1000 on your host system will have **full read/write access** to OpenCloud data. - -In multi-user or shared hosting environments: - -1. Isolate the host user (e.g., dedicated service account) -2. Restrict SSH/shell access appropriately -3. Use additional filesystem-level security (SELinux, AppArmor) -4. Regularly audit file access - - ::: - -## Environment Variables for Persistence - -```bash -# In .env file -OC_CONFIG_DIR=/your/local/path/opencloud/config -OC_DATA_DIR=/your/local/path/opencloud/data -OC_LOG_DIR=/your/local/path/opencloud/logs - -# Ensure these directories exist with correct permissions -``` +## Further reading -If these variables are not set, Docker will use unnamed volumes that persist only as long as containers are not removed. +For more information about Docker storage, see the official Docker documentation: -## See Also +- [Volumes](https://docs.docker.com/storage/volumes/) +- [Bind mounts](https://docs.docker.com/engine/storage/bind-mounts/) -- **[Production Considerations](./production-considerations.md)** – Volume mounting setup -- **[Docker documentation on volumes](https://docs.docker.com/storage/volumes/)** -- **[Linux permission quick reference](https://en.wikipedia.org/wiki/File-system_permissions)** +For backup recommendations, see [Backup and recovery](../../../maintenance/backup.md). diff --git a/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/docker-compose-base.md b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/docker-compose-base.md index dfda07f4..c66c65f5 100644 --- a/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/docker-compose-base.md +++ b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/docker-compose-base.md @@ -10,7 +10,7 @@ draft: false Install an internet-facing OpenCloud instance with automatic SSL certificates using Docker Compose's integrated Traefik reverse proxy. -This is the **recommended deployment path** for most new OpenCloud installations. Traefik automatically manages Let's Encrypt SSL certificates, eliminating the need to manage a separate reverse proxy. +This is the recommended deployment path for most new OpenCloud installations. Traefik automatically manages Let's Encrypt SSL certificates, eliminating the need to manage a separate reverse proxy. This installation guide is written for Ubuntu and Debian systems. The software can also be installed on other Linux distributions, but commands and package managers may differ. @@ -158,10 +158,10 @@ After starting OpenCloud, verify that services are running and SSL certificates ## Next Steps -- **[Verify TLS Certificates](./verify-tls-certificates.md)** – Validate staging certificates and switch to production -- **[Production Setup Considerations](./production-considerations.md)** – Persistent storage, backups, and production best practices -- **[Configure Keycloak](./keycloak-deployment.md)** (optional) – Add Keycloak for enterprise identity management -- **[Configure Authentication](../../../configuration/authentication-and-user-management/)** – User management and identity provider integration +- [Verify TLS Certificates](./verify-tls-certificates.md) – Validate staging certificates and switch to production +- [Production Setup Considerations](./production-considerations.md) – Persistent storage, backups, and production best practices +- [Configure Keycloak](./keycloak-deployment.md) (optional) – Add Keycloak for enterprise identity management +- [Configure Authentication](../../../configuration/authentication-and-user-management/) – User management and identity provider integration ## Troubleshooting diff --git a/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/volume-permissions.md b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/volume-permissions.md index a1a55284..abbcd167 100644 --- a/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/volume-permissions.md +++ b/versioned_docs/version-4.0/admin/getting-started/container/docker-compose/volume-permissions.md @@ -13,8 +13,8 @@ This guide explains how to properly configure filesystem permissions for OpenClo OpenCloud containers run as a non-root user with: -- **UID (User ID):** 1000 -- **GID (Group ID):** 1000 +- UID (User ID): 1000 +- GID (Group ID): 1000 This is the user that reads and writes to all data, configuration, and cache directories within the container. @@ -78,18 +78,18 @@ ls /your/local/path/opencloud/config cd /your/local/path/opencloud/data ``` -This is the **most common case** and requires minimal configuration. +This is the most common case and requires minimal configuration. ### UID mismatch scenarios -**Problem:** Your host system's UID 1000 is assigned to a different user (or doesn't exist). +Problem: Your host system's UID 1000 is assigned to a different user (or doesn't exist). ```bash cat /etc/passwd | grep 1000 # (empty or shows different user) ``` -**Solution:** Create a dedicated service user or adjust permissions: +Solution: Create a dedicated service user or adjust permissions: ```bash # Option 1: Create a dedicated user for OpenCloud @@ -114,7 +114,7 @@ sudo chmod -R 0700 /your/local/path/opencloud - Group members: no access - Others: no access -**Use case:** Maximum security; only the container user can access. +Use case: Maximum security; only the container user can access. ### More permissive: 0750 (rwxr-x---) @@ -126,7 +126,7 @@ sudo chmod -R 0750 /your/local/path/opencloud - Group members: read, execute - Others: no access -**Use case:** Allows other group members to read (useful for backups, monitoring). +Use case: Allows other group members to read (useful for backups, monitoring). ### Caution: 0755 (rwxr-xr-x) @@ -136,7 +136,7 @@ sudo chmod -R 0755 /your/local/path/opencloud - Everyone can read and list directories -**Warning:** Not recommended for data directories containing sensitive information. +Warning: Not recommended for data directories containing sensitive information. ## Bind Mounts vs Named Volumes @@ -148,13 +148,13 @@ OC_CONFIG_DIR=/your/local/path/opencloud/config OC_DATA_DIR=/your/local/path/opencloud/data ``` -**Advantages:** +Advantages: - Full control over permissions and ownership - Easy to backup - Direct host filesystem access -**You must manually manage permissions.** +You must manually manage permissions. ### Named Volumes (Docker-managed) @@ -165,12 +165,12 @@ If not set, Docker creates automatic volumes: docker volume ls ``` -**Advantages:** +Advantages: - Docker manages permissions automatically - Docker handles backup/restore -**Disadvantages:** +Disadvantages: - Harder to access directly - Less control over ownership @@ -214,7 +214,7 @@ sudo chmod -R 0700 /your/local/path/opencloud ## Security Considerations :::caution -UID 1000 on your host system will have **full read/write access** to OpenCloud data. +UID 1000 on your host system will have full read/write access to OpenCloud data. In multi-user or shared hosting environments: @@ -240,6 +240,6 @@ If these variables are not set, Docker will use unnamed volumes that persist onl ## See Also -- **[Production Considerations](./production-considerations.md)** – Volume mounting setup -- **[Docker documentation on volumes](https://docs.docker.com/storage/volumes/)** -- **[Linux permission quick reference](https://en.wikipedia.org/wiki/File-system_permissions)** +- [Production Considerations](./production-considerations.md) – Volume mounting setup +- [Docker documentation on volumes](https://docs.docker.com/storage/volumes/) +- [Linux permission quick reference](https://en.wikipedia.org/wiki/File-system_permissions)