Standard deployment with Traefik reverse proxy and Let's Encrypt certificates
External proxy support for environments with existing reverse proxies (like Nginx, Caddy, etc.)
Collabora Online integration for document editing

Quick Start Guide

Prerequisites

Docker and Docker Compose installed
Domain names pointing to your server (for production deployment)
Basic understanding of Docker Compose concepts

Local Development

Clone the repository:

git clone https://github.com/opencloud-eu/opencloud-compose.git
cd opencloud-compose

Create environment file:
```
cp .env.example .env
```
Note

: 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.

Configure deployment options:

You can deploy using explicit -f flags:

docker compose -f docker-compose.yml -f traefik/opencloud.yml up -d

Or by uncommenting the COMPOSE_FILE variable in .env:

COMPOSE_FILE=docker-compose.yml:traefik/opencloud.yml

Then simply run:

docker compose up -d

Add local domains to /etc/hosts:

127.0.0.1 cloud.opencloud.test
127.0.0.1 traefik.opencloud.test

Access OpenCloud:
- URL: https://cloud.opencloud.test
- Username: admin
- Password: admin (or as configured in .env)

Production Deployment

Edit the .env file and configure:
- Domain names
- Admin password
- SSL certificate email
- Storage paths

Configure deployment options in .env:

COMPOSE_FILE=docker-compose.yml:docker-compose.collabora.yml:traefik/opencloud.yml:traefik/collabora.yml

Start OpenCloud:
```
docker compose up -d
```

Deployment Options

With Collabora Online

Include Collabora for document editing using either method:

Using -f flags:

docker compose -f docker-compose.yml -f docker-compose.collabora.yml -f traefik/opencloud.yml -f traefik/collabora.yml up -d

Or by setting in .env:

COMPOSE_FILE=docker-compose.yml:docker-compose.collabora.yml:traefik/opencloud.yml:traefik/collabora.yml

Add to /etc/hosts for local development:

127.0.0.1 collabora.opencloud.test
127.0.0.1 wopiserver.opencloud.test

Behind External Proxy

If you already have a reverse proxy (Nginx, Caddy, etc.), use either method:

Using -f flags:

docker compose -f docker-compose.yml -f docker-compose.collabora.yml -f external-proxy/opencloud.yml -f external-proxy/collabora.yml up -d

Or by setting in .env:

COMPOSE_FILE=docker-compose.yml:docker-compose.collabora.yml:external-proxy/opencloud.yml:external-proxy/collabora.yml

This exposes the necessary ports:

OpenCloud: 9200
Collabora: 9980
WOPI server: 9300

Configuration

Environment Variables

The configuration is managed through environment variables in the .env file:

We provide .env.example as a template with documentation for all options
Your personal .env file is ignored by git to keep sensitive information private
This pattern allows everyone to customize their deployment without affecting the repository

Key variables:

Variable	Description	Default
`COMPOSE_FILE`	Colon-separated list of compose files to use	(commented out)
`OC_DOMAIN`	OpenCloud domain	cloud.opencloud.test
`OC_DOCKER_TAG`	OpenCloud image tag	latest
`ADMIN_PASSWORD`	Admin password	admin
`OC_CONFIG_DIR`	Config directory path	(Docker volume)
`OC_DATA_DIR`	Data directory path	(Docker volume)
`INSECURE`	Skip certificate validation	true
`COLLABORA_DOMAIN`	Collabora domain	collabora.opencloud.test
`WOPISERVER_DOMAIN`	WOPI server domain	wopiserver.opencloud.test

See .env.example for all available options and their documentation.

Persistent Storage

For production, configure persistent storage:

OC_CONFIG_DIR=/path/to/opencloud/config
OC_DATA_DIR=/path/to/opencloud/data

Ensure proper permissions:

mkdir -p /path/to/opencloud/{config,data}
chown -R 1000:1000 /path/to/opencloud

Compose File Structure

This repository uses a modular approach with multiple compose files:

docker-compose.yml - Core OpenCloud service
docker-compose.collabora.yml - Collabora Online integration
traefik/ - Traefik reverse proxy configurations
external-proxy/ - Configuration for external reverse proxies
config/ - Configuration files for OpenCloud

Advanced Usage

Understanding the COMPOSE_FILE Variable

The COMPOSE_FILE environment variable is a powerful way to manage complex Docker Compose deployments:

It uses colons (:) as separators between files (configurable with COMPOSE_PATH_SEPARATOR)
Files are processed in order, with later files overriding settings from earlier ones
It allows you to run just docker compose up -d without specifying -f flags
Perfect for automation, CI/CD pipelines, and consistent deployments

Example configuration for production with Collabora:

COMPOSE_FILE=docker-compose.yml:docker-compose.collabora.yml:traefik/opencloud.yml:traefik/collabora.yml

Automation and GitOps

For automated deployments, using the COMPOSE_FILE variable in .env is recommended:

COMPOSE_FILE=docker-compose.yml:docker-compose.collabora.yml:traefik/opencloud.yml:traefik/collabora.yml

This allows tools like Ansible or CI/CD pipelines to deploy the stack without modifying the compose files.

Custom compose file overrides

You can create custom compose files to override specific settings after creating a custom directory:

mkdir -p custom

Then create a docker-compose.override.yml file in the custom directory with your overrides.

This folder is ignored by git, allowing you to customize your deployment without affecting the repository. This can be useful in scenarios like portainer where the git repository is configured as a stack.

You can for example add custom labels to the OpenCloud service:

services:
  opencloud:
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.opencloud.rule=Host(`cloud.opencloud.test`)"
      - "traefik.http.services.opencloud.loadbalancer.server.port=80"
      - "traefik.http.routers.opencloud.tls.certresolver=my-resolver"

Troubleshooting

Common Issues

SSL Certificate Errors: For local development, accept self-signed certificates by visiting each domain directly in your browser.
Port Conflicts: If you have services already using ports 80/443, use the external proxy configuration.
Permission Issues: Ensure data and config directories have proper permissions (owned by user/group 1000).

Logs

View logs with:

docker compose logs -f

For specific service logs:

docker compose logs -f opencloud

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the GNU General Public License v3 (GPLv3).