136 lines
3.4 KiB
Markdown
136 lines
3.4 KiB
Markdown
# EmbarGit Auth and Deployment Design
|
|
|
|
This document captures current decisions about deployment topology and CLI scope for Phase 1.
|
|
|
|
## Goals
|
|
|
|
- Keep EmbarGit self-hosted and private by default.
|
|
- Expose only the read-only share-link viewer to the public internet.
|
|
- Make the CLI responsible for generating deployment files and setup scaffolding.
|
|
- Keep Phase 1 scope minimal and shippable.
|
|
|
|
## Non-Goals
|
|
|
|
- Any admin authentication layer (no Tailscale, no Pocket ID, no login screen).
|
|
- Reverse proxy generation or examples.
|
|
- Cloudflare integration or documentation.
|
|
- Replacing Forgejo.
|
|
- Adding a SaaS control plane.
|
|
- Requiring end users to join Tailscale in order to view shared code.
|
|
- Designing a browser-based admin UX before the backend and deployment scaffolding exist.
|
|
|
|
## Core Architecture
|
|
|
|
EmbarGit has two distinct surfaces:
|
|
|
|
- Public viewer surface for read-only share links.
|
|
- Private admin and operational surface for owners/operators.
|
|
|
|
The security boundary is the public/private split, not an auth layer.
|
|
|
|
```ascii
|
|
Public internet
|
|
|
|
|
v
|
|
Read-only viewer endpoint
|
|
|
|
|
+--> Embargo/EmbarGit app
|
|
|
|
|
+--> Private Forgejo API
|
|
|
|
|
+--> Private database
|
|
|
|
Admin/operator access
|
|
|
|
|
v
|
|
Direct host or VPN (operator's responsibility)
|
|
|
|
|
v
|
|
Private admin panel
|
|
|
|
|
+--> Forgejo admin
|
|
+--> Postgres
|
|
+--> Logs / backups / host access
|
|
```
|
|
|
|
## Deployment
|
|
|
|
Single deployment mode: Docker Compose.
|
|
|
|
- EmbarGit service
|
|
- Forgejo service
|
|
- PostgreSQL service
|
|
- Network definitions for private/public separation
|
|
|
|
Admin access security is the operator's responsibility (VPN, firewall rules, etc). EmbarGit does not enforce or scaffold this in Phase 1.
|
|
|
|
## Public Viewer Rules
|
|
|
|
- Share links are public resources by design.
|
|
- Public access must be read-only.
|
|
- Public access must not expose admin routes, database ports, or Forgejo admin surfaces.
|
|
- Viewer requests must validate:
|
|
- link token
|
|
- expiration
|
|
- revoked state
|
|
- snapshot binding
|
|
|
|
The viewer should be the only public application surface that emits code content.
|
|
|
|
## CLI Responsibilities
|
|
|
|
The CLI is the primary way to scaffold a deployment.
|
|
|
|
### `init`
|
|
|
|
`init` should:
|
|
|
|
- prompt for domain / hostnames
|
|
- generate `.env`
|
|
- generate `docker-compose.yml`
|
|
- generate Forgejo and Embargo service defaults
|
|
|
|
### `start`, `stop`, `status`
|
|
|
|
Thin wrappers around Docker Compose.
|
|
|
|
### CLI UX
|
|
|
|
- Use spinners for long-running steps.
|
|
- Use prompts for interactive configuration.
|
|
- Keep output terse and actionable.
|
|
- Present generated files clearly after initialization.
|
|
|
|
## Configuration Outputs
|
|
|
|
Expected outputs from `init`:
|
|
|
|
- `.env`
|
|
- `docker-compose.yml`
|
|
|
|
## Data and Auth Model
|
|
|
|
- Share links are tied to immutable snapshots.
|
|
- Grants must resolve to a specific `commit_sha`.
|
|
- Viewer endpoints must never accept arbitrary repo/ref selection.
|
|
|
|
## Repo Implementation Impact
|
|
|
|
Active surfaces:
|
|
|
|
- CLI entrypoint: `packages/cli/src/index.ts`
|
|
- Command stubs: `packages/cli/src/commands/*`
|
|
- Config generators: `packages/cli/src/generators/*`
|
|
- Shared constants/types: `packages/shared/src/*`
|
|
- Service entrypoint: `packages/service/src/index.ts`
|
|
|
|
Next implementation work:
|
|
|
|
1. Make `init` generate configs via interactive prompts
|
|
2. Add a CLI prompt/spinner library
|
|
3. Expand shared types for deployment config
|
|
4. Wire the service to use the generated config
|
|
|
|
## Open Questions
|
|
|
|
- Should the public viewer be mounted at a fixed path like `/share/*` or a dedicated hostname?
|