# 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).