The minimalistic document archiving platform.
feat(processes): added worker vs web processes (#577)
Corentin Thomassetbd3e321eb721
diff --git a/.changeset/big-geese-boil.md b/.changeset/big-geese-boil.mdnew file mode 100644index 00000000..c6508e86--- /dev/null+++ b/.changeset/big-geese-boil.md@@ -0,0 +1,5 @@+---+"@papra/docker": patch+---++Improved graceful shutdowndiff --git a/.changeset/sad-facts-see.md b/.changeset/sad-facts-see.mdnew file mode 100644index 00000000..e67fd706--- /dev/null+++ b/.changeset/sad-facts-see.md@@ -0,0 +1,5 @@+---+"@papra/docker": patch+---++Added the possibility to start either just the api, just the workers, or both (default)diff --git a/apps/papra-server/fly.toml b/apps/papra-server/fly.tomlindex d89dcf7d..82ae3c27 100644--- a/apps/papra-server/fly.toml+++ b/apps/papra-server/fly.toml@@ -12,7 +12,8 @@ release_command = "pnpm --silent migrate:up:prod"strategy = "rolling"[processes]-web = "pnpm --silent start"+web = "PROCESS_MODE=web pnpm --silent start"+worker = "PROCESS_MODE=worker pnpm --silent start"[http_service]internal_port = 1221diff --git a/apps/papra-server/src/index.ts b/apps/papra-server/src/index.tsindex b7ea8801..80ca0f6a 100644--- a/apps/papra-server/src/index.ts+++ b/apps/papra-server/src/index.ts@@ -3,6 +3,7 @@ import process, { env } from 'node:process';import { serve } from '@hono/node-server';import { setupDatabase } from './modules/app/database/database';import { ensureLocalDatabaseDirectoryExists } from './modules/app/database/database.services';+import { createGracefulShutdownService } from './modules/app/graceful-shutdown/graceful-shutdown.services';import { createServer } from './modules/app/server';import { parseConfig } from './modules/config/config';import { createDocumentStorageService } from './modules/documents/storage/documents.storage.services';@@ -15,86 +16,81 @@ const logger = createLogger({ namespace: 'app-server' });const { config } = await parseConfig({ env });+const isWebMode = config.processMode === 'all' || config.processMode === 'web';+const isWorkerMode = config.processMode === 'all' || config.processMode === 'worker';++logger.info({ processMode: config.processMode, isWebMode, isWorkerMode }, 'Starting application');++// Shutdown callback collector+const shutdownService = createGracefulShutdownService({ logger });+const { registerShutdownHandler } = shutdownService;+await ensureLocalDatabaseDirectoryExists({ config });-const { db, client } = setupDatabase(config.database);+const { db } = setupDatabase({ ...config.database, registerShutdownHandler });const documentsStorageService = createDocumentStorageService({ documentStorageConfig: config.documentsStorage });const taskServices = createTaskServices({ config });await taskServices.initialize();-const { app } = await createServer({ config, db, taskServices, documentsStorageService });--const server = serve(- {- fetch: app.fetch,- port: config.server.port,- hostname: config.server.hostname,- },- ({ port }) => logger.info({ port }, 'Server started'),-);--if (config.ingestionFolder.isEnabled) {- const { startWatchingIngestionFolders } = createIngestionFolderWatcher({- taskServices,- config,- db,- documentsStorageService,+if (isWebMode) {+ const { app } = await createServer({ config, db, taskServices, documentsStorageService });++ const server = serve(+ {+ fetch: app.fetch,+ port: config.server.port,+ hostname: config.server.hostname,+ },+ ({ port }) => logger.info({ port }, 'Server started'),+ );++ registerShutdownHandler({+ id: 'web-server-close',+ handler: () => {+ server.close();+ },});-- await startWatchingIngestionFolders();}-await registerTaskDefinitions({ taskServices, db, config, documentsStorageService });+if (isWorkerMode) {+ if (config.ingestionFolder.isEnabled) {+ const { startWatchingIngestionFolders } = createIngestionFolderWatcher({+ taskServices,+ config,+ db,+ documentsStorageService,+ });-taskServices.start();+ await startWatchingIngestionFolders();+ }++ await registerTaskDefinitions({ taskServices, db, config, documentsStorageService });++ taskServices.start();+ logger.info('Worker started');+}// Global error handlersprocess.on('uncaughtException', (error) => {logger.error({ error }, 'Uncaught exception');-- // Give the logger time to flush before exiting- setTimeout(() => {- process.exit(1);- }, 1000);+ setTimeout(() => process.exit(1), 1000); // Give the logger time to flush before exiting});process.on('unhandledRejection', (error) => {- logger.error({- error,- }, 'Unhandled promise rejection');-- // Give the logger time to flush before exiting- setTimeout(() => {- process.exit(1);- }, 1000);+ logger.error({ error }, 'Unhandled promise rejection');+ setTimeout(() => process.exit(1), 1000); // Give the logger time to flush before exiting});// Graceful shutdown handler-process.on('SIGINT', async () => {- logger.info('Received SIGINT, shutting down gracefully...');-- try {- server.close();- client.close();- logger.info('Server shut down successfully');- } catch (error) {- logger.error({ error }, 'Error during shutdown');- }+async function gracefulShutdown(signal: string) {+ logger.info({ signal }, 'Received shutdown signal, shutting down gracefully...');- process.exit(0);-});--process.on('SIGTERM', async () => {- logger.info('Received SIGTERM, shutting down gracefully...');-- try {- server.close();- client.close();- logger.info('Server shut down successfully');- } catch (error) {- logger.error({ error }, 'Error during shutdown');- }+ await shutdownService.executeShutdownHandlers();+ logger.info('Shutdown complete, exiting process');process.exit(0);-});+}++process.on('SIGINT', () => void gracefulShutdown('SIGINT'));+process.on('SIGTERM', () => void gracefulShutdown('SIGTERM'));diff --git a/apps/papra-server/src/modules/app/database/database.ts b/apps/papra-server/src/modules/app/database/database.tsindex 7a692ec8..66b017d2 100644--- a/apps/papra-server/src/modules/app/database/database.ts+++ b/apps/papra-server/src/modules/app/database/database.ts@@ -1,3 +1,4 @@+import type { ShutdownHandlerRegistration } from '../graceful-shutdown/graceful-shutdown.services';import { createClient } from '@libsql/client';import { drizzle } from 'drizzle-orm/libsql';@@ -7,15 +8,22 @@ function setupDatabase({url,authToken,encryptionKey,+ registerShutdownHandler,}: {url: string;authToken?: string;encryptionKey?: string;+ registerShutdownHandler?: ShutdownHandlerRegistration;}) {const client = createClient({ url, authToken, encryptionKey });const db = drizzle(client);+ registerShutdownHandler?.({+ id: 'database-client-close',+ handler: () => client.close(),+ });+return {db,client,diff --git a/apps/papra-server/src/modules/app/graceful-shutdown/graceful-shutdown.services.ts b/apps/papra-server/src/modules/app/graceful-shutdown/graceful-shutdown.services.tsnew file mode 100644index 00000000..1c8e961b--- /dev/null+++ b/apps/papra-server/src/modules/app/graceful-shutdown/graceful-shutdown.services.ts@@ -0,0 +1,34 @@+import type { Logger } from '../../shared/logger/logger';+import { createLogger } from '../../shared/logger/logger';++export type ShutdownHandlerConfig = {+ id: string;+ handler: () => void | Promise<void>;+};+export type ShutdownHandlerRegistration = (handlerConfig: ShutdownHandlerConfig) => void;++export function createGracefulShutdownService({ logger = createLogger({ namespace: 'graceful-shutdown' }) }: { logger?: Logger } = {}) {+ const shutdownHandlers: ShutdownHandlerConfig[] = [];++ return {+ registerShutdownHandler: (handler: ShutdownHandlerConfig) => {+ shutdownHandlers.push(handler);+ },++ async executeShutdownHandlers() {+ logger.info('Executing shutdown handlers');++ await Promise.allSettled(+ shutdownHandlers.map(async ({ handler, id }) => {+ try {+ await handler();+ } catch (error) {+ logger.error({ error, id }, 'Error executing shutdown handler');+ }+ }),+ );++ logger.info('All shutdown handlers executed');+ },+ };+}diff --git a/apps/papra-server/src/modules/config/config.ts b/apps/papra-server/src/modules/config/config.tsindex 56812c93..6f394d1f 100644--- a/apps/papra-server/src/modules/config/config.ts+++ b/apps/papra-server/src/modules/config/config.ts@@ -28,6 +28,12 @@ export const configDefinition = {default: 'development',env: 'NODE_ENV',},+ processMode: {+ doc: 'The process mode: "all" runs both web and worker, "web" runs only the API server, "worker" runs only background tasks',+ schema: z.enum(['all', 'web', 'worker']),+ default: 'all',+ env: 'PROCESS_MODE',+ },appBaseUrl: {doc: 'The base URL of the application. Will override the client baseUrl and server baseUrl when set. Use this one over the client and server baseUrl when the server is serving the client assets (like in docker).',schema: z.string().url().optional(),