Merge pull request #6 from michaelstingl/add-documentation

Add documentation
2026-06-08 12:10:05 +08:00 · 2025-05-19 22:12:28 +02:00
parent da432a9891 14f8cee581
commit 1ae2c546c5
1 changed files with 226 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,226 @@
+# OpenCloud Compose
+
+This repository provides Docker Compose configurations for deploying OpenCloud in various environments.
+
+## Overview
+
+OpenCloud Compose offers a modular approach to deploying OpenCloud with several configuration options:
+
+- **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
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/opencloud-eu/opencloud-compose.git
+   cd opencloud-compose
+   ```
+
+2. **Create environment file**:
+   ```bash
+   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.
+
+3. **Configure deployment options**:
+   
+   You can deploy using explicit `-f` flags:
+   ```bash
+   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:
+   ```bash
+   docker compose up -d
+   ```
+
+4. **Add local domains to `/etc/hosts`**:
+   ```
+   127.0.0.1 cloud.opencloud.test
+   127.0.0.1 traefik.opencloud.test
+   ```
+
+5. **Access OpenCloud**:
+   - URL: https://cloud.opencloud.test
+   - Username: `admin`
+   - Password: `admin` (or as configured in `.env`)
+
+### Production Deployment
+
+1. **Edit the `.env` file** and configure:
+   - Domain names
+   - Admin password
+   - SSL certificate email
+   - Storage paths
+
+2. **Configure deployment options** in `.env`:
+   ```
+   COMPOSE_FILE=docker-compose.yml:docker-compose.collabora.yml:traefik/opencloud.yml:traefik/collabora.yml
+   ```
+
+3. **Start OpenCloud**:
+   ```bash
+   docker compose up -d
+   ```
+
+## Deployment Options
+
+### With Collabora Online
+
+Include Collabora for document editing using either method:
+
+Using `-f` flags:
+```bash
+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:
+```bash
+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:
+```bash
+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.
+
+## 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:
+```bash
+docker compose logs -f
+```
+
+For specific service logs:
+```bash
+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).