139 lines
5.8 KiB
Markdown
139 lines
5.8 KiB
Markdown
# Rose Ash
|
|
|
|
Monorepo for the Rose Ash cooperative platform — six Quart microservices sharing a common infrastructure layer, a single PostgreSQL database, and an ActivityPub federation layer.
|
|
|
|
## Services
|
|
|
|
| Service | URL | Description |
|
|
|---------|-----|-------------|
|
|
| **blog** | blog.rose-ash.com | Content management, Ghost sync, navigation, editor |
|
|
| **market** | market.rose-ash.com | Product listings, scraping, market pages |
|
|
| **cart** | cart.rose-ash.com | Shopping cart, checkout, orders, SumUp payments |
|
|
| **events** | events.rose-ash.com | Calendar, event entries, container widgets |
|
|
| **federation** | federation.rose-ash.com | OAuth2 authorization server, ActivityPub hub, social features |
|
|
| **account** | account.rose-ash.com | User dashboard, newsletters, tickets, bookings |
|
|
|
|
All services are Python 3.11 / Quart apps served by Hypercorn, deployed as a Docker Swarm stack.
|
|
|
|
## Repository structure
|
|
|
|
```
|
|
rose-ash/
|
|
├── shared/ # Common code: models, services, infrastructure, templates
|
|
│ ├── models/ # Canonical SQLAlchemy ORM models (all domains)
|
|
│ ├── services/ # Domain service implementations + registry
|
|
│ ├── contracts/ # DTOs, protocols, widget contracts
|
|
│ ├── infrastructure/ # App factory, OAuth, ActivityPub, fragments, Jinja setup
|
|
│ ├── templates/ # Shared base templates and partials
|
|
│ ├── static/ # Shared CSS, JS, images
|
|
│ ├── editor/ # Prose editor (Node build, blog only)
|
|
│ └── alembic/ # Database migrations
|
|
├── blog/ # Blog app
|
|
├── market/ # Market app
|
|
├── cart/ # Cart app
|
|
├── events/ # Events app
|
|
├── federation/ # Federation app
|
|
├── account/ # Account app
|
|
├── docker-compose.yml # Swarm stack definition
|
|
├── deploy.sh # Local build + restart script
|
|
├── .gitea/workflows/ # CI: build changed apps + deploy
|
|
├── _config/ # Runtime config (app-config.yaml)
|
|
├── schema.sql # Reference schema snapshot
|
|
└── .env # Environment variables (not committed)
|
|
```
|
|
|
|
Each app follows the same layout:
|
|
|
|
```
|
|
{app}/
|
|
├── app.py # App entry point (creates Quart app)
|
|
├── path_setup.py # Adds project root + app dir to sys.path
|
|
├── entrypoint.sh # Container entrypoint (wait for DB, run migrations, start)
|
|
├── Dockerfile # Build instructions (monorepo context)
|
|
├── bp/ # Blueprints (routes, handlers)
|
|
│ └── fragments/ # Fragment endpoints for cross-app composition
|
|
├── models/ # Re-export stubs pointing to shared/models/
|
|
├── services/ # App-specific service wiring
|
|
├── templates/ # App-specific templates (override shared/)
|
|
└── config/ # App-specific config
|
|
```
|
|
|
|
## Key architecture patterns
|
|
|
|
**Shared models** — All ORM models live in `shared/models/`. Each app's `models/` directory contains thin re-export stubs. `factory.py` imports all six apps' models at startup so SQLAlchemy relationship references resolve across domains.
|
|
|
|
**Service contracts** — Apps communicate through typed protocols (`shared/contracts/protocols.py`) and frozen dataclass DTOs (`shared/contracts/dtos.py`), wired via a singleton registry (`shared/services/registry.py`). No direct HTTP calls between apps for domain logic.
|
|
|
|
**Fragment composition** — Apps expose HTML fragments at `/internal/fragments/<type>` for cross-app UI composition. The blog fetches cart, account, navigation, and event fragments to compose its pages. Fragments are cached in Redis with short TTLs.
|
|
|
|
**OAuth SSO** — Federation is the OAuth2 authorization server. All other apps are OAuth clients with per-app first-party session cookies (Safari ITP compatible). Login/callback/logout routes are auto-registered via `shared/infrastructure/oauth.py`.
|
|
|
|
**ActivityPub** — Each app has its own AP actor (virtual projection of the same keypair). The federation app is the social hub (timeline, compose, follow, notifications). Activities are emitted to `ap_activities` table and processed by `EventProcessor`.
|
|
|
|
## Development
|
|
|
|
### Quick deploy (skip CI)
|
|
|
|
```bash
|
|
# Rebuild + restart one app
|
|
./deploy.sh blog
|
|
|
|
# Rebuild + restart multiple apps
|
|
./deploy.sh blog market
|
|
|
|
# Rebuild all
|
|
./deploy.sh --all
|
|
|
|
# Auto-detect changes from git
|
|
./deploy.sh
|
|
```
|
|
|
|
### Full stack deploy
|
|
|
|
```bash
|
|
source .env
|
|
docker stack deploy -c docker-compose.yml coop
|
|
```
|
|
|
|
### Build a single app image
|
|
|
|
```bash
|
|
docker build -f blog/Dockerfile -t registry.rose-ash.com:5000/blog:latest .
|
|
```
|
|
|
|
### Run migrations
|
|
|
|
Migrations run automatically on the **blog** service startup when `RUN_MIGRATIONS=true` is set (only blog runs migrations; all other apps skip them).
|
|
|
|
```bash
|
|
# Manual migration
|
|
docker exec -it $(docker ps -qf name=coop_blog) bash -c "cd shared && alembic upgrade head"
|
|
```
|
|
|
|
## CI/CD
|
|
|
|
A single Gitea Actions workflow (`.gitea/workflows/ci.yml`) handles all six apps:
|
|
|
|
1. Detects which files changed since the last deploy
|
|
2. If `shared/` or `docker-compose.yml` changed, rebuilds all apps
|
|
3. Otherwise rebuilds only apps with changes (or missing images)
|
|
4. Pushes images to the private registry
|
|
5. Runs `docker stack deploy` to update the swarm
|
|
|
|
### Required secrets
|
|
|
|
| Secret | Value |
|
|
|--------|-------|
|
|
| `DEPLOY_SSH_KEY` | Private SSH key for root access to the deploy host |
|
|
| `DEPLOY_HOST` | Hostname or IP of the deploy server |
|
|
|
|
## Infrastructure
|
|
|
|
- **Runtime**: Python 3.11, Quart (async Flask), Hypercorn
|
|
- **Database**: PostgreSQL 16 (shared by all apps)
|
|
- **Cache**: Redis 7 (page cache, fragment cache, sessions)
|
|
- **Orchestration**: Docker Swarm
|
|
- **Registry**: `registry.rose-ash.com:5000`
|
|
- **CI**: Gitea Actions
|
|
- **Reverse proxy**: Caddy (external, not in this repo)
|