Application Bootstrap & PocketBase Integration

Relevant source files

• cmd/intercmd.go
• cmd/serve_nonwindows.go
• cmd/serve_windows.go
• cmd/version.go
• cmd/winsc_nonwindows.go
• cmd/winsc_windows.go
• internal/app/app.go
• internal/certificate/service_deps.go
• internal/domain/dtos/notify.go
• internal/notify/service.go
• internal/rest/handlers/notifications.go
• internal/rest/handlers/workflows.go
• internal/rest/routes/routes.go
• internal/scheduler/scheduler.go
• internal/settings/pbhook.go
• internal/settings/pbsettings.go
• internal/settings/pbstore.go
• internal/settings/settings.go
• internal/workflow/engine/deps.go
• internal/workflow/pbhook.go
• internal/workflow/pbjob.go
• internal/workflow/service_deps.go
• internal/workflow/service_inst.go
• main.go
• pkg/core/deployer/providers/wangsu-cdnpro/wangsu_cdnpro.go
• pkg/core/notifier/providers/mattermost/mattermost.go
• pkg/sdk3rd/matrix/client.go
• pkg/sdk3rd/nginxproxymanager/types.go

This page documents the initialization sequence of the Certimate application, focusing on how the Go backend integrates with PocketBase to provide a unified identity, database, and API layer. It covers the singleton pattern used for the application instance, the command-line interface, and the lifecycle hooks that wire together the scheduler, workflow engine, and the embedded React UI.

Application Entry Point

The application entry point is located in main.go. It initializes the PocketBase instance and configures the execution environment. Certimate extends the standard PocketBase distribution by adding custom commands and binding logic to the server's lifecycle events.

The Singleton Pattern

Certimate uses a singleton pattern to manage the application state and ensure that only one instance of the PocketBase app is active. This is managed via the internal/app package.

• app.GetApp(): Returns the global application instance, cast to *pocketbase.PocketBase in main.go main.go28
• Metadata: Constants such as AppName and AppVersion (currently 0.4.29) are defined here to be used across the system internal/app/app.go3-7

Command Line Configuration

Certimate configures PocketBase to provide a streamlined experience:

1. Exec Args Validation: The application checks for execution arguments at startup, logging an error if the serve command is missing main.go29-33
2. Custom Commands: Three specific commands are added to the PocketBase root command:
   • NewInternalCommand: Provides internal utility functions, including the intercmd/certapply subprocess used for ACME isolation main.go39
   • NewVersionCommand: Prints version, Go runtime, and build metadata main.go40 cmd/version.go13-24
   • NewWinscCommand: Handles Windows service installation and management main.go41
3. Migrations: The migratecmd plugin is registered to handle database schema changes, with auto-migration enabled during development based on the binary path main.go35-37

Diagram: Bootstrap Flow "Main Entry to PocketBase Initialization"

Sources: main.go27-94 main.go39-41 internal/app/app.go3-7 cmd/version.go13-24

---

PocketBase Lifecycle Hooks

Certimate heavily utilizes PocketBase's OnServe, OnBootstrap, and OnTerminate hooks to initialize and clean up background services.

OnServe Hook

When the server starts (via the serve command), the following subsystems are initialized:

1. Static UI: The embedded React frontend is served via apis.Static from the ui.DistDirFS with a high priority (999) and Gzip compression main.go55-63
2. Subsystem Setup:
   • scheduler.Setup(): Starts the cron-based certificate renewal checks main.go66 internal/scheduler/scheduler.go12-28
   • workflow.Setup(): Initializes the workflow dispatcher and processing queues main.go67
3. API Routes: routes.BindRouter(e.Router) registers custom REST endpoints main.go68 This function wires together the repository layer and service layer for Certificates, Workflows, Statistics, and Notifications internal/rest/routes/routes.go23-42

OnBootstrap Hook

This hook is used to ensure system settings are present upon run. It specifically calls settings.Setup() to initialize application-level configurations after the default bootstrap sequence main.go46-53

OnTerminate Hook

To ensure graceful shutdowns, the OnTerminate hook is used:

• Workflow Teardown: workflow.Teardown() is called to stop the dispatcher and ensure no orphaned processes are left running, provided the app was successfully bootstrapped main.go78-84

Table: Lifecycle Hook Responsibilities

Hook	Function Called	Responsibility
OnBootstrap	settings.Setup()	Configures system settings and defaults main.go51
OnServe	scheduler.Setup()	Starts the cron runner for automated tasks main.go66
OnServe	workflow.Setup()	Initializes the WorkflowDispatcher and pending queues main.go67
OnServe	routes.BindRouter()	Mounts custom REST handlers (Certificates, Workflows, etc.) main.go68
OnTerminate	workflow.Teardown()	Stops active workflow executions and cleans up resources main.go80

Sources: main.go45-85 internal/scheduler/scheduler.go12-28 internal/rest/routes/routes.go23-42

---

Multi-Process Isolation (mproc)

For ACME certificate issuance, Certimate uses a multi-process isolation pattern. This prevents potential memory leaks or crashes in the ACME client (lego) from affecting the main application.

intercmd/certapply Subprocess

The intercmd/certapply command is a dedicated internal command that handles the actual ACME challenge and issuance cmd/intercmd.go20-29

1. Execution: It is registered via NewInternalCommand and executed as certapply cmd/intercmd.go26-31
2. Receiver: The subprocess uses mproc.NewReceiver to handle IPC. It reads an InData struct containing ACMEAccount and ObtainCertificateRequest cmd/intercmd.go69-80
3. Lego Integration: It initializes the ACME client via certacme.NewACMEClientWithAccount and calls ObtainCertificate cmd/intercmd.go93-104
4. Logging: The subprocess redirects lego logs to a wrapped JSON handler (hookStdLog) so they can be parsed correctly by the main process cmd/intercmd.go37-62 cmd/intercmd.go91

Diagram: Multi-Process Isolation Flow "ACME Isolation via intercmd Subprocess"

Sources: cmd/intercmd.go20-125 cmd/intercmd.go80-112

---

Windows Service Support

Certimate includes native support for running as a Windows service via the winsc command group main.go41

• Commands: The NewWinscCommand provides subcommands to manage the service lifecycle (install, uninstall, start, stop) main.go41
• Cross-Platform Implementation:
  • On Windows, it uses the golang.org/x/sys/windows/svc package to interface with the Service Control Manager.
  • On non-Windows platforms, these commands return a "not supported" message cmd/winsc_nonwindows.go13-24
• Execution: The cmd.Serve(pb) function handles the actual startup logic, distinguishing between standard serve and Windows service contexts main.go87-93

Sources: main.go39-41 main.go87-93 cmd/winsc_nonwindows.go13-24

---

Embedded UI Integration

Certimate is distributed as a single binary. This is achieved by embedding the compiled React frontend into the Go binary using Go's embed package.

Static Asset Serving

The server binds the root path and sub-paths to the static file server using apis.Static(ui.DistDirFS, false) main.go57-59

• ui.DistDirFS: This variable (exported from the ui package) contains the production build of the React application main.go22
• Gzip Compression: The static route is wrapped with apis.Gzip() to optimize asset delivery main.go59

Diagram: Code Entity Mapping (UI to Backend) "Static Asset Embedding & Serving"

Sources: main.go55-63 main.go22