b0esche_cloud/README.md

# b0esche.cloud

A self-hosted, SaaS-style cloud storage and document platform with a Go backend and Flutter web frontend.

🌐 **Live:** [b0esche.cloud](https://b0esche.cloud)

## Architecture

```
┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Flutter Web    │────▶│   Go Backend    │────▶│   PostgreSQL    │
│  (b0esche_cloud)│     │   (go_cloud)    │     │                 │
└─────────────────┘     └────────┬────────┘     └─────────────────┘
                                 │
                    ┌────────────┼────────────┐
                    ▼            ▼            ▼
             ┌──────────┐ ┌──────────┐ ┌──────────┐
             │Nextcloud │ │Collabora │ │  Traefik │
             │(Storage) │ │ (Office) │ │ (Proxy)  │
             └──────────┘ └──────────┘ └──────────┘
```

## Project Structure

```
b0esche_cloud/
├── b0esche_cloud/          # Flutter web frontend
│   ├── lib/
│   │   ├── blocs/          # BLoC state management
│   │   ├── models/         # Data models
│   │   ├── pages/          # UI pages
│   │   ├── repositories/   # Data repositories
│   │   ├── services/       # API services
│   │   ├── theme/          # App theming
│   │   └── widgets/        # Reusable widgets
│   └── web/                # Web assets
├── go_cloud/               # Go backend
│   ├── cmd/api/            # Main entry point
│   ├── internal/
│   │   ├── auth/           # Authentication (OIDC, Passkeys)
│   │   ├── files/          # File management
│   │   ├── org/            # Organization management
│   │   ├── storage/        # Nextcloud/WebDAV integration
│   │   ├── http/           # HTTP handlers & WOPI
│   │   └── ...
│   ├── migrations/         # Database migrations
│   └── pkg/jwt/            # JWT utilities
├── scripts/                # Deployment & operations scripts
└── docs/                   # Documentation
    └── AUTH.md             # Authentication system docs
```

## Features

- 🔐 **Authentication**: OIDC via Nextcloud + WebAuthn Passkeys
- 📁 **File Management**: Upload, download, organize files
- 👥 **Organizations**: Multi-tenant with roles (Owner, Admin, Member)
- 📝 **Document Viewing**: PDF viewer, Office document preview
- 🔄 **Real-time Sync**: Nextcloud/WebDAV backend storage
- 🚀 **Auto-deployment**: Daily 3AM deployments via GitLab webhooks

## Prerequisites

- Go 1.21+
- Flutter 3.10+
- Docker & Docker Compose
- PostgreSQL 15+

## Local Development

### Quick Start

```bash
# Start everything
./scripts/dev-all.sh
```

### Manual Setup

**Backend:**
```bash
cd go_cloud
cp .env.example .env
# Edit .env with your configuration
go run ./cmd/api
```

**Frontend:**
```bash
cd b0esche_cloud
flutter pub get
flutter run -d chrome
```

## Configuration

### Backend Environment Variables

| Variable | Description |
|----------|-------------|
| `SERVER_ADDR` | Server address (default: `:8080`) |
| `DATABASE_URL` | PostgreSQL connection string |
| `JWT_SECRET` | Secret for JWT signing |
| `OIDC_ISSUER_URL` | OIDC provider URL |
| `OIDC_CLIENT_ID` | OIDC client ID |
| `OIDC_CLIENT_SECRET` | OIDC client secret |
| `NEXTCLOUD_URL` | Nextcloud instance URL |
| `NEXTCLOUD_USERNAME` | Nextcloud admin username |
| `NEXTCLOUD_PASSWORD` | Nextcloud admin password |
| `COLLABORA_URL` | Collabora Online URL |

## Production Deployment

The project runs on a VPS with Docker containers behind Traefik reverse proxy.

### Services & Domains

| Domain | Service |
|--------|---------|
| `www.b0esche.cloud` | Flutter Web (Nginx) |
| `go.b0esche.cloud` | Go API Backend |
| `storage.b0esche.cloud` | Nextcloud (Storage + OIDC) |
| `of.b0esche.cloud` | Collabora Online (Office) |

### Server Directory Structure

```
/opt/
├── traefik/          # Reverse proxy + SSL
├── go/               # Go backend + PostgreSQL
├── flutter/          # Flutter web build + Nginx
├── scripts/          # Operations scripts
└── auto-deploy/      # Auto-deployment workspace
```

### Server Scripts

| Script | Description |
|--------|-------------|
| `auto-deploy.sh` | Daily automated deployment (runs at 3AM) |
| `deploy-now.sh` | Trigger immediate deployment |
| `backup.sh` | Full backup (DB, configs, volumes) |
| `monitor.sh` | Health monitoring & alerts |
| `webhook-server.py` | GitLab webhook receiver |

### Deployment Commands

```bash
# Trigger immediate deploy
ssh b0esche-cloud '/opt/scripts/deploy-now.sh'

# Check backend logs
ssh b0esche-cloud 'docker logs go-backend -f'

# Check service status
ssh b0esche-cloud 'docker ps --format "table {{.Names}}\t{{.Status}}"'

# Health checks
curl -s https://go.b0esche.cloud/health
curl -s https://www.b0esche.cloud | grep -o '<title>.*</title>'
```

### Starting Services (Manual)

```bash
# Start all services in order
ssh b0esche-cloud 'cd /opt/traefik && docker-compose up -d'
ssh b0esche-cloud 'cd /opt/go && docker-compose up -d'
ssh b0esche-cloud 'cd /opt/flutter && docker-compose up -d'
```

## Database Migrations

Migrations are in `go_cloud/migrations/`:

```bash
cd go_cloud
go run github.com/pressly/goose/v3/cmd/goose@latest postgres "$DATABASE_URL" up
```

## Backup & Recovery

Backups run daily and include:
- PostgreSQL database dumps
- Nextcloud database
- Traefik certificates
- Docker volumes
- Configuration files

Backups are retained for 30 days.

```bash
# Manual backup
ssh b0esche-cloud '/opt/scripts/backup.sh'
```

## Testing

```bash
# Backend tests
cd go_cloud && go test ./...

# Frontend tests
cd b0esche_cloud && flutter test
```

## Tech Stack

| Component | Technology |
|-----------|------------|
| Frontend | Flutter Web, BLoC |
| Backend | Go, Chi Router |
| Database | PostgreSQL |
| Storage | Nextcloud (WebDAV) |
| Office | Collabora Online |
| Auth | OIDC, WebAuthn |
| Proxy | Traefik |
| CI/CD | GitLab + Webhooks |

## Documentation

| Document | Description |
|----------|-------------|
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System architecture, components, data flows |
| [API.md](docs/API.md) | Complete API endpoint reference |
| [AUTH.md](docs/AUTH.md) | Authentication system (Passkeys, OIDC, roles) |
| [SECURITY.md](docs/SECURITY.md) | Security architecture, hardening, best practices |
| [DEVELOPMENT.md](docs/DEVELOPMENT.md) | Local setup, coding conventions, testing |
| [DEPLOYMENT.md](docs/DEPLOYMENT.md) | Production deployment, operations, troubleshooting |

## License

Private project - All rights reserved