homeio

Purpose

This module displays installed Docker Compose apps, loads the App Store catalog, and runs install/update/uninstall/start/stop/restart operations. Long-running operations are persisted in PostgreSQL and streamed to the UI with SSE.

Locations

• Server-side: lib/server/modules/apps/, lib/server/modules/store/, lib/server/modules/docker/
• Client-side: modules/apps/
• Routes: app/api/v1/apps/, app/api/v1/store/, app/api/v1/docker/

Key Files

Public API

• Server functions: listInstalledApps(), startStoreOperation(), getStoreOperation(), subscribeToStoreOperation()
• Client hooks: useInstalledApps(), useStoreCatalog(), useStoreApp(), useStoreOperation(), useStoreActions(), useStoreSources()
• Components: AppGrid, AppStore, AppLogsDialog, CustomAppInstallDialog, UninstallAppDialog

Contracts

• lib/shared/contracts/apps.ts
• lib/shared/contracts/docker.ts

Database Tables

• apps
• app_stacks
• app_operations
• custom_store_apps

API Routes Owned

• GET /api/v1/apps
• POST /api/v1/apps/[appId]/start
• POST /api/v1/apps/[appId]/stop
• POST /api/v1/apps/[appId]/restart
• POST /api/v1/apps/[appId]/check-updates
• GET /api/v1/apps/[appId]/logs/stream
• GET /api/v1/store/apps
• GET /api/v1/store/apps/[appId]
• GET /api/v1/store/apps/[appId]/compose
• PATCH /api/v1/store/apps/[appId]/settings
• POST /api/v1/store/apps/[appId]/install
• POST /api/v1/store/apps/[appId]/update
• POST /api/v1/store/apps/[appId]/redeploy
• POST /api/v1/store/apps/[appId]/uninstall
• GET /api/v1/store/operations/[operationId]
• GET /api/v1/store/operations/[operationId]/stream
• GET/POST/PATCH/DELETE /api/v1/store/sources*
• POST /api/v1/store/custom-apps/install
• POST /api/v1/store/check-updates

Known Issues

• lib/server/modules/apps/operations.ts is over 1,200 lines and runs operations in-process via queueMicrotask().
• There is no external operation queue. startStoreOperation() uses an in-memory per-app guard and serverEnv.STORE_MAX_CONCURRENT_OPERATIONS global cap.
• Routes in this domain are protected by requireApiSession() except documented OAuth-style bootstrap routes outside this module.
• Demo app data and CDN icon URLs are hardcoded in lib/server/modules/apps/service.ts.

How To Extend

To add a new operation:

1. Add action/status types in lib/shared/contracts/apps.ts.
2. Add persistence fields only if needed in lib/server/db/schema.ts.
3. Add operation logic in lib/server/modules/apps/operations.ts, keeping changes narrow.
4. Preserve the existing StoreOperationError behavior for same-app conflicts (409) and global caps (429).
5. Add a route under app/api/v1/store/apps/[appId]/.
6. Add a client action in modules/apps/hooks/useStoreActions.ts.
7. Add UI in modules/apps/components/.
8. Add tests beside the route and in lib/server/modules/apps/__tests__/.