README
¶
AppOS Backend
PocketBase-based application server with custom business logic compiled into a single Go binary.
Architecture
- PocketBase as application framework (auth, DB, realtime, admin UI)
- Custom routes for Docker operations, proxy management, terminal, backup
- Asynq + Redis for persistent async task processing (embedded worker)
Prerequisites
- Go 1.26+
- Redis (for Asynq task queue)
- Docker (host access via socket)
Development
# Install dependencies
go mod tidy
# Run with hot-reload (requires air: go install github.com/air-verse/air@latest)
air
# Or run directly
go run cmd/appos/main.go serve --dev
# Build
go build -o appos cmd/appos/main.go
# Run production binary
./appos serve --http=0.0.0.0:8090
OpenAPI Maintenance
OpenAPI docs are embedded into the appos binary and served at:
/openapi(Swagger UI)/openapi/spec(raw YAML)
Primary spec file:
backend/docs/openapi/api.yaml(generated merged artifact)
Recommended workflow after route changes:
# from project root
make openapi-sync
Available commands:
make openapi-gen— regenerateext-api.yamlfrom custom route source (generated custom-route spec for/api/ext/*,/api/servers/*,/api/apps*,/api/actions*,/api/pipelines*,/api/software/local*)make openapi-merge— mergeext-api.yaml+native-api.yamlintoapi.yamlmake openapi-check— fail when custom route/spec drift or duplicate YAML keys existmake openapi-sync— run generate + merge + check in order
Maintenance rules:
- Keep
native-api.yamlmanually curated. - Treat
ext-api.yamlas the generated custom-route spec (do not edit manually). - Treat
api.yamlas generated merge artifact (do not edit manually). - Rebuild backend (
make build backend) after spec updates so embedded docs are refreshed.
Project Structure
backend/
├── cmd/appos/main.go # Entry point: PocketBase + extensions
├── internal/
│ ├── routes/ # Custom API route handlers
│ │ ├── routes.go # Route registration
│ │ ├── apps.go # App lifecycle (deploy, restart, stop)
│ │ ├── proxy.go # Reverse proxy management
│ │ ├── system.go # Metrics, terminal, files
│ │ └── backup.go # Backup/restore
│ ├── hooks/hooks.go # PocketBase event hooks
│ ├── worker/worker.go # Asynq task worker (embedded)
│ ├── docker/docker.go # Docker Engine API client
│ ├── terminal/terminal.go # WebSocket + PTY terminal
│ └── migrations/ # PocketBase auto-migrations
├── .air.toml # Hot-reload config
└── .env.example
API Endpoints
Custom Routes
Custom business APIs use two prefixes:
/api/ext/*for most extension domains/api/servers/*for server runtime operations (shell/files/ops/containers)
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /apps/deploy |
user | Deploy application |
| POST | /apps/{id}/restart |
user | Restart application |
| POST | /apps/{id}/stop |
user | Stop application |
| DELETE | /apps/{id} |
user | Delete application |
| GET | /apps/{id}/logs |
user | Stream app logs |
| GET | /apps/{id}/env |
user | Get environment vars |
| PUT | /apps/{id}/env |
user | Update environment vars |
| POST | /proxy/domains |
admin | Add domain binding |
| GET | /proxy/domains |
admin | List domains |
| DELETE | /proxy/domains/{domain} |
admin | Remove domain |
| POST | /proxy/domains/{domain}/ssl |
admin | Request SSL cert |
| POST | /proxy/reload |
admin | Reload proxy |
| GET | /system/metrics |
admin | System metrics |
| GET | /system/terminal |
admin | WebSocket terminal |
| GET | /system/files |
admin | File browser |
| POST | /backup/create |
admin | Create backup |
| POST | /backup/restore |
admin | Restore backup |
| GET | /backup/list |
admin | List backups |
Built-in PocketBase Routes
/api/collections/*— CRUD for all collections/api/realtime— SSE subscriptions/_/— Admin UI
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
appos
command
|
|
|
appos/bootstrap
Package bootstrap registers PocketBase event hooks for AppOS business logic.
|
Package bootstrap registers PocketBase event hooks for AppOS business logic. |
|
openapi
command
|
|
|
docs
|
|
|
openapi
Package openapidocs embeds the AppOS OpenAPI specification so it can be served directly from the appos binary without depending on nginx or any external static file server.
|
Package openapidocs embeds the AppOS OpenAPI specification so it can be served directly from the appos binary without depending on nginx or any external static file server. |
|
domain
|
|
|
audit
Package audit provides a unified helper for writing operation audit records.
|
Package audit provides a unified helper for writing operation audit records. |
|
config/sharedenv
Package sharedenv provides normalized shared environment read models and lookup services for config-domain consumers.
|
Package sharedenv provides normalized shared environment read models and lookup services for config-domain consumers. |
|
config/sysconfig
Package settings provides a centralized helper for reading and writing grouped configuration values stored in the custom_settings PocketBase collection.
|
Package settings provides a centralized helper for reading and writing grouped configuration values stored in the custom_settings PocketBase collection. |
|
config/uiconfig
Package uiconfig manages UI configuration preferences for the AppOS dashboard.
|
Package uiconfig manages UI configuration preferences for the AppOS dashboard. |
|
groups
Package groups implements the Groups domain — cross-type resource organisation.
|
Package groups implements the Groups domain — cross-type resource organisation. |
|
iac
Package iac defines the IaC workspace domain boundary.
|
Package iac defines the IaC workspace domain boundary. |
|
routes
Package routes — IaC API (Epic 14: IaC File Management)
|
Package routes — IaC API (Epic 14: IaC File Management) |
|
software
Package software implements the Software Delivery domain for AppOS.
|
Package software implements the Software Delivery domain for AppOS. |
|
software/catalog
Package catalog loads and resolves Software Delivery component templates and catalogs.
|
Package catalog loads and resolves Software Delivery component templates and catalogs. |
|
software/executor
Package executor provides SSH-based execution of Software Delivery template actions against managed remote servers.
|
Package executor provides SSH-based execution of Software Delivery template actions against managed remote servers. |
|
software/readiness
Package readiness evaluates target readiness against a PreflightSpec.
|
Package readiness evaluates target readiness against a PreflightSpec. |
|
space
Package space implements the Space domain — the user's personal file workspace.
|
Package space implements the Space domain — the user's personal file workspace. |
|
terminal
Package terminal provides the core abstractions for interactive terminal sessions.
|
Package terminal provides the core abstractions for interactive terminal sessions. |
|
topics
Package topics implements the Topic aggregate and its domain rules.
|
Package topics implements the Topic aggregate and its domain rules. |
|
worker
Package worker manages the embedded Asynq task worker.
|
Package worker manages the embedded Asynq task worker. |
|
infra
|
|
|
cronutil
Package cronutil provides a reusable structured logging wrapper for AppOS-maintained PocketBase cron job handlers.
|
Package cronutil provides a reusable structured logging wrapper for AppOS-maintained PocketBase cron job handlers. |
|
crypto
Package crypto provides AES-256-GCM encryption/decryption for secret values.
|
Package crypto provides AES-256-GCM encryption/decryption for secret values. |
|
docker
Package docker provides Docker operations for AppOS.
|
Package docker provides Docker operations for AppOS. |
|
egress
Package egress provides AppOS shared outbound network policy runtime.
|
Package egress provides AppOS shared outbound network policy runtime. |
|
egress/fetchstore
Package fetchstore provides the canonical fetch-for-store execution runtime beneath the shared egress parent domain.
|
Package fetchstore provides the canonical fetch-for-store execution runtime beneath the shared egress parent domain. |
|
filesvc
Package filesvc provides a local filesystem service boundary for backend domains that need path-scoped file and directory operations.
|
Package filesvc provides a local filesystem service boundary for backend domains that need path-scoped file and directory operations. |
|
fileutil
Package fileutil provides filesystem helpers shared by the File API routes and the deploy flow.
|
Package fileutil provides filesystem helpers shared by the File API routes and the deploy flow. |
|
gitops
Package gitops owns concrete git network execution helpers.
|
Package gitops owns concrete git network execution helpers. |
|
migrations
Package migrations contains PocketBase Go migrations for AppOS custom collections.
|
Package migrations contains PocketBase Go migrations for AppOS custom collections. |
|
remoteruntime
Package remoteruntime is the execution-layer anchor for remote runtime egress.
|
Package remoteruntime is the execution-layer anchor for remote runtime egress. |
|
remoteshell
Package remoteshell owns remote shell execution decisions and transport.
|
Package remoteshell owns remote shell execution decisions and transport. |
|
supervisor
Package supervisor provides a client for supervisord XML-RPC API and process resource monitoring via system commands.
|
Package supervisor provides a client for supervisord XML-RPC API and process resource monitoring via system commands. |
|
tunnelcore
Package tunnel provides a reverse-SSH tunnel entry point for local servers behind NAT.
|
Package tunnel provides a reverse-SSH tunnel entry point for local servers behind NAT. |
Click to show internal directories.
Click to hide internal directories.