Add docs, scripts, and update README
- Added docs/AUTH.md with authentication system documentation - Added server scripts (auto-deploy, backup, monitor, webhook-server) - Updated README with deployment info and project structure - Added gitignore for backup archives
This commit is contained in:
Leon Bösche
254
README.md
254
README.md
@@ -1,149 +1,227 @@
|
||||
# b0esche.cloud
|
||||
|
||||
A self-hosted, SaaS-style document platform with Go backend and Flutter web frontend.
|
||||
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
|
||||
|
||||
- `go_cloud/`: Go backend (control plane) with REST API
|
||||
- `b0esche_cloud/`: Flutter web frontend with BLoC architecture
|
||||
- Supporting services: Nextcloud (storage), Collabora (editing), PostgreSQL (database)
|
||||
```
|
||||
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
|
||||
│ │ ├── viewmodels/ # View models
|
||||
│ │ └── 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 and Docker Compose
|
||||
- PostgreSQL (or Docker)
|
||||
- Nextcloud instance
|
||||
- Collabora Online instance
|
||||
- Docker & Docker Compose
|
||||
- PostgreSQL 15+
|
||||
|
||||
## Local Development Setup
|
||||
## Local Development
|
||||
|
||||
### 1. Start Supporting Services
|
||||
|
||||
Use Docker Compose to start PostgreSQL, Nextcloud, and Collabora:
|
||||
### Quick Start
|
||||
|
||||
```bash
|
||||
docker-compose up -d db nextcloud collabora
|
||||
# Start everything
|
||||
./scripts/dev-all.sh
|
||||
```
|
||||
|
||||
### 2. Backend Setup
|
||||
### Manual Setup
|
||||
|
||||
**Backend:**
|
||||
```bash
|
||||
cd go_cloud
|
||||
cp .env.example .env
|
||||
# Edit .env with your configuration (DB URL, Nextcloud URL, etc.)
|
||||
# Edit .env with your configuration
|
||||
go run ./cmd/api
|
||||
```
|
||||
|
||||
Or use the provided script:
|
||||
|
||||
```bash
|
||||
./scripts/dev-backend.sh
|
||||
```
|
||||
|
||||
### 3. Frontend Setup
|
||||
|
||||
**Frontend:**
|
||||
```bash
|
||||
cd b0esche_cloud
|
||||
flutter pub get
|
||||
flutter run -d chrome
|
||||
```
|
||||
|
||||
Or use the script:
|
||||
|
||||
```bash
|
||||
./scripts/dev-frontend.sh
|
||||
```
|
||||
|
||||
### 4. Full Development Environment
|
||||
|
||||
To start everything:
|
||||
|
||||
```bash
|
||||
./scripts/dev-all.sh
|
||||
```
|
||||
|
||||
This will bring up all services, backend, and frontend.
|
||||
|
||||
## Configuration
|
||||
|
||||
### Backend (.env)
|
||||
### Backend Environment Variables
|
||||
|
||||
Copy `go_cloud/.env.example` to `go_cloud/.env` and fill in:
|
||||
| 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 |
|
||||
|
||||
- `DATABASE_URL`: PostgreSQL connection string
|
||||
- `JWT_SECRET`: Random secret for JWT signing
|
||||
- `OIDC_*`: OIDC provider settings
|
||||
- `NEXTCLOUD_*`: Nextcloud API settings
|
||||
- `COLLABORA_*`: Collabora settings
|
||||
## Production Deployment
|
||||
|
||||
### Frontend
|
||||
The project runs on a VPS with Docker containers behind Traefik reverse proxy.
|
||||
|
||||
The frontend uses build-time environment variables for API base URL. For dev, it's hardcoded in `ApiClient` constructor.
|
||||
### Services & Domains
|
||||
|
||||
For production builds, update accordingly.
|
||||
| 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) |
|
||||
|
||||
## Running Tests
|
||||
### Server Directory Structure
|
||||
|
||||
### Backend
|
||||
|
||||
```bash
|
||||
cd go_cloud
|
||||
go test ./...
|
||||
```
|
||||
/opt/
|
||||
├── traefik/ # Reverse proxy + SSL
|
||||
├── go/ # Go backend + PostgreSQL
|
||||
├── flutter/ # Flutter web build + Nginx
|
||||
├── scripts/ # Operations scripts
|
||||
└── auto-deploy/ # Auto-deployment workspace
|
||||
```
|
||||
|
||||
### Frontend
|
||||
### 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
|
||||
cd b0esche_cloud
|
||||
flutter test
|
||||
# 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>'
|
||||
```
|
||||
|
||||
## Building for Production
|
||||
|
||||
### Backend
|
||||
### Starting Services (Manual)
|
||||
|
||||
```bash
|
||||
cd go_cloud
|
||||
go build -o bin/api ./cmd/api
|
||||
```
|
||||
|
||||
### Frontend
|
||||
|
||||
```bash
|
||||
cd b0esche_cloud
|
||||
flutter build web
|
||||
# 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/`.
|
||||
|
||||
To apply:
|
||||
Migrations are in `go_cloud/migrations/`:
|
||||
|
||||
```bash
|
||||
# Dev
|
||||
cd go_cloud
|
||||
go run github.com/pressly/goose/v3/cmd/goose@latest postgres "$DATABASE_URL" up
|
||||
|
||||
# Production
|
||||
# Use your deployment tool to run the migration command
|
||||
```
|
||||
|
||||
## Backup Strategy
|
||||
## Backup & Recovery
|
||||
|
||||
- **Database**: Regular PostgreSQL dumps of orgs, memberships, activities
|
||||
- **Files**: Nextcloud/S3 backups handled at storage layer
|
||||
- **Recovery**: Restore DB, then files; Go control plane is stateless
|
||||
Backups run daily and include:
|
||||
- PostgreSQL database dumps
|
||||
- Nextcloud database
|
||||
- Traefik certificates
|
||||
- Docker volumes
|
||||
- Configuration files
|
||||
|
||||
## Contributing
|
||||
Backups are retained for 30 days.
|
||||
|
||||
1. Clone the repo
|
||||
2. Follow local setup
|
||||
3. Make changes
|
||||
4. Run tests
|
||||
5. Submit PR
|
||||
```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
|
||||
|
||||
- [AUTH.md](docs/AUTH.md) - Complete authentication system documentation (Passkeys, OIDC, roles)
|
||||
|
||||
## License
|
||||
|
||||
[License here]
|
||||
Private project - All rights reserved
|
||||
|
||||
Reference in New Issue
Block a user