How picosh/pico works
Main Components
• Clients: End users interact with the system using SSH, rsync, scp, or sftp from their terminals.
• Service Endpoints (Microservices):
– Auth Service: (Located under cmd/auth & pkg/apps/auth) handles user authentication and access.
– Pages Service (pgs): (cmd/pgs, pkg/apps/pgs) enables static site hosting with TLS management.
– Feeds Service: (cmd/feeds, pkg/apps/feeds) processes RSS feed subscription and email notifications.
– Pastes Service: (cmd/pastes, pkg/apps/pastes) supports code snippet uploads.
– Prose Service: (cmd/prose, pkg/apps/prose) powers the blog platform.
– Pipe Service: (cmd/pipe, pkg/apps/pipe) manages authenticated Unix pipes over SSH.
– Pico (and possibly tuns): (cmd/pico, pkg/apps/pico, pkg/tunkit) handles lightweight service tasks and creating secure tunnels.
• Infrastructure Components:
– Reverse Proxy / TLS Termination: The “caddy” folder with multiple Caddyfile variants indicates a Caddy-based proxy used to manage TLS and route incoming requests.
– Docker & Deployment: Dockerfiles at the project root, within the “bouncer” directory, and in “caddy” denote containerization. Additionally, the various docker-compose files (e.g., docker-compose.yml, docker-compose.prod.yml) and CI/CD GitHub workflows show a container-based deployment process.
• Shared Libraries and Utilities:
– “pkg” directory: Houses the shared code (database access, file handling, storage abstractions, SSH utilities, etc.) that support all microservices.
– “scripts”: Contains administrative or migration scripts (database migrations, file-size sync, etc.).
– “sql”: Contains schema and migration SQL files, indicating use of relational databases (notably Postgres as seen in pkg/db/postgres).
Relationships and Interactions
• How incoming requests are first handled by the reverse proxy (Caddy) which then dispatches to each specific service container.
• For services that depend on a database (e.g., pgs, prose), illustrate the connection to the database layer which uses Postgres (or other storage backends as abstracted by pkg/db).
Architectural Patterns and Technologies
• Microservices Pattern: Each major functionality (auth, pages, feeds, pastes, prose, pipe, etc.) exists as a separate command/service with its own SSH and web interfaces.
• Containerization: Extensive Dockerfile usage across services and utilizing docker-compose for orchestration.
• Reverse Proxy/TLS Termination: The Caddy server configuration files indicate layered handling of web requests with different domain rules.
• Shared Code Libraries: Emphasis on the “pkg” folder reflecting a modular design with shared services such as storage abstraction, SSH command handling, and templating for the web front-ends.
• CI/CD Integration: Built-in configuration files for GitHub Actions to run tests, builds, and deploy through automated workflows.
Elements
– Clients → Caddy (reverse proxy/TLS termination) → Specific Service
– Service → Database/Storage (for persistence)
– Service interactions if any exist (e.g., if one service triggers an action in another).
• Configuration dependencies (for instance, Docker setups, GitHub CI/CD workflows) that are critical to the deployment lifecycle.