3.4 KiB
3.4 KiB
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.
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:
.envdocker-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:
- Make
initgenerate configs via interactive prompts - Add a CLI prompt/spinner library
- Expand shared types for deployment config
- 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?