Sync-in · Sovereign platform for file storage, sharing, synchronization, and collaboration.
TypeScript cloud-alternativecollaborationcollaborative-editingdropboxfile-serverfile-sharingfile-storagefile-syncfull-text-searchhomelabnextcloudon-premiseopen-sourceprivacy-firstprivate-cloudrealtimesecureself-hostedstorage-serverwebdav
feat(backend:availability): expose health endpoints and add Docker health checks
johaven952681254ec8
diff --git a/Dockerfile b/Dockerfileindex 328b8711..811f16ce 100644--- a/Dockerfile+++ b/Dockerfile@@ -23,6 +23,9 @@ ENV NODE_ENV=productionENV NPM_CONFIG_UPDATE_NOTIFIER=falseENV PUID=8888ENV PGID=8888+ENV SYNC_IN_HEALTHCHECK_URL=http://127.0.0.1:8080/healthz/readyEXPOSE 8080+HEALTHCHECK --interval=30s --timeout=5s --start-period=60s --retries=3 \+ CMD ["node", "server/infrastructure/availability/scripts/check-health.js"]ENTRYPOINT ["./entrypoint.sh"]-CMD ["/bin/sh", "sync-in-server.sh"]\ No newline at end of file+CMD ["/bin/sh", "sync-in-server.sh"]diff --git a/backend/src/infrastructure/availability/availability.constants.ts b/backend/src/infrastructure/availability/availability.constants.tsindex 74bc0e1d..b4c45b44 100644--- a/backend/src/infrastructure/availability/availability.constants.ts+++ b/backend/src/infrastructure/availability/availability.constants.ts@@ -6,3 +6,14 @@ export const INFRASTRUCTURE_DEPENDENCY = {CACHE: 'cache',WEBSOCKET: 'websocket'} as const satisfies Record<string, AvailabilityDependency>++export const AVAILABILITY_ROUTE = {+ BASE: '/healthz',+ LIVE: 'live',+ READY: 'ready'+} as const++export const AVAILABILITY_STATUS = {+ OK: 'ok',+ UNAVAILABLE: 'unavailable'+} as constdiff --git a/backend/src/infrastructure/availability/availability.controller.spec.ts b/backend/src/infrastructure/availability/availability.controller.spec.tsnew file mode 100644index 00000000..74a44816--- /dev/null+++ b/backend/src/infrastructure/availability/availability.controller.spec.ts@@ -0,0 +1,51 @@+import { HttpStatus, ServiceUnavailableException } from '@nestjs/common'+import { Reflector } from '@nestjs/core'+import { AUTH_TOKEN_SKIP } from '../../authentication/decorators/auth-token-skip.decorator'+import { AVAILABILITY_ROUTE, AVAILABILITY_STATUS, INFRASTRUCTURE_DEPENDENCY } from './availability.constants'+import { AvailabilityController } from './availability.controller'+import { AVAILABILITY_SKIP } from './availability.decorator'+import { Availability } from './availability.service'++describe(AvailabilityController.name, () => {+ let availability: Availability+ let controller: AvailabilityController++ beforeEach(() => {+ availability = new Availability()+ controller = new AvailabilityController(availability)+ })++ it(`GET ${AVAILABILITY_ROUTE.BASE}/${AVAILABILITY_ROUTE.LIVE} reports a live process independently of dependencies`, () => {+ availability.register(INFRASTRUCTURE_DEPENDENCY.DATABASE)++ expect(controller.liveness()).toEqual({ status: AVAILABILITY_STATUS.OK })+ })++ it(`GET ${AVAILABILITY_ROUTE.BASE}/${AVAILABILITY_ROUTE.READY} reports an available service`, () => {+ availability.register(INFRASTRUCTURE_DEPENDENCY.DATABASE, true)++ expect(controller.readiness()).toEqual({ status: AVAILABILITY_STATUS.OK })+ })++ it(`GET ${AVAILABILITY_ROUTE.BASE}/${AVAILABILITY_ROUTE.READY} reports an unavailable service`, () => {+ availability.register(INFRASTRUCTURE_DEPENDENCY.DATABASE)++ let error: unknown+ try {+ controller.readiness()+ } catch (e) {+ error = e+ }++ expect(error).toBeInstanceOf(ServiceUnavailableException)+ expect((error as ServiceUnavailableException).getStatus()).toBe(HttpStatus.SERVICE_UNAVAILABLE)+ expect((error as ServiceUnavailableException).getResponse()).toEqual({ status: AVAILABILITY_STATUS.UNAVAILABLE })+ })++ it('bypasses authentication and availability guards', () => {+ const reflector = new Reflector()++ expect(reflector.get<boolean>(AUTH_TOKEN_SKIP, AvailabilityController)).toBe(true)+ expect(reflector.get<boolean>(AVAILABILITY_SKIP, AvailabilityController)).toBe(true)+ })+})diff --git a/backend/src/infrastructure/availability/availability.controller.ts b/backend/src/infrastructure/availability/availability.controller.tsnew file mode 100644index 00000000..380139fe--- /dev/null+++ b/backend/src/infrastructure/availability/availability.controller.ts@@ -0,0 +1,28 @@+import { Controller, Get, Header, ServiceUnavailableException } from '@nestjs/common'+import { AuthTokenSkip } from '../../authentication/decorators/auth-token-skip.decorator'+import { AVAILABILITY_ROUTE, AVAILABILITY_STATUS } from './availability.constants'+import { AvailabilitySkip } from './availability.decorator'+import { Availability } from './availability.service'+import { AvailabilityHealthResponse } from './availability.interfaces'++@Controller(AVAILABILITY_ROUTE.BASE)+@AuthTokenSkip()+@AvailabilitySkip()+export class AvailabilityController {+ constructor(private readonly availability: Availability) {}++ @Get(AVAILABILITY_ROUTE.LIVE)+ @Header('Cache-Control', 'no-store')+ liveness(): AvailabilityHealthResponse {+ return { status: AVAILABILITY_STATUS.OK }+ }++ @Get(AVAILABILITY_ROUTE.READY)+ @Header('Cache-Control', 'no-store')+ readiness(): AvailabilityHealthResponse {+ if (!this.availability.allAvailable()) {+ throw new ServiceUnavailableException({ status: AVAILABILITY_STATUS.UNAVAILABLE })+ }+ return { status: AVAILABILITY_STATUS.OK }+ }+}diff --git a/backend/src/infrastructure/availability/availability.interfaces.ts b/backend/src/infrastructure/availability/availability.interfaces.tsindex 8e4f193b..f9fdd89e 100644--- a/backend/src/infrastructure/availability/availability.interfaces.ts+++ b/backend/src/infrastructure/availability/availability.interfaces.ts@@ -1 +1,4 @@+export interface AvailabilityHealthResponse {+ status: 'ok' | 'unavailable'+}export type AvailabilityDependency = 'database' | 'cache' | 'websocket'diff --git a/backend/src/infrastructure/availability/availability.md b/backend/src/infrastructure/availability/availability.mdindex fa0de929..57eb6cfd 100644--- a/backend/src/infrastructure/availability/availability.md+++ b/backend/src/infrastructure/availability/availability.md@@ -19,3 +19,27 @@ monitored dependencies, such as `/api/auth/logout`.`INFRASTRUCTURE_CONNECTION_RETRY_DELAY` provides the shared delay used by infrastructure reconnection loops. The availability module only stores andexposes state; it does not reconnect dependencies itself.++## Health endpoints++`GET /healthz/live` reports whether the HTTP process is alive. It always returns HTTP `200` with `{ "status": "ok" }` once the server is listening.++`GET /healthz/ready` reports whether every registered dependency is available. It returns HTTP `200` with `{ "status": "ok" }` when the service is+ready and HTTP `503` with `{ "status": "unavailable" }` otherwise.++Both endpoints are unauthenticated, bypass `AvailabilityGuard`, return `Cache-Control: no-store`, and expose no dependency details.++## Docker health checks++The Sync-in container image runs the compiled `server/infrastructure/availability/scripts/check-health.js` script, which sends a `GET` request to+`/healthz/ready`. By default, the check runs inside the container against `http://127.0.0.1:8080/healthz/ready`, so it is independent of the published+host port and Docker Compose DNS. The target can be overridden with the `SYNC_IN_HEALTHCHECK_URL` container environment variable.++The script does not follow redirects and accepts only HTTP `200` as a successful result. Any other HTTP status, a missing or invalid target URL, or a+network error causes the Docker health check to fail.++The Docker Compose setup also checks that MariaDB accepts connections and has initialized InnoDB before starting Sync-in. The existing startup retry+loop remains in place for direct `docker run` usage and as an additional safeguard.++An unavailable registered dependency marks the Sync-in container as unhealthy while the application keeps running and attempts to reconnect. Docker's+`restart: always` policy restarts a stopped container; the health status alone does not trigger a restart.diff --git a/backend/src/infrastructure/availability/availability.module.ts b/backend/src/infrastructure/availability/availability.module.tsindex d78119b5..b4aff4bf 100644--- a/backend/src/infrastructure/availability/availability.module.ts+++ b/backend/src/infrastructure/availability/availability.module.ts@@ -1,10 +1,12 @@import { Global, Module } from '@nestjs/common'import { APP_GUARD } from '@nestjs/core'+import { AvailabilityController } from './availability.controller'import { AvailabilityGuard } from './availability.guard'import { Availability } from './availability.service'@Global()@Module({+ controllers: [AvailabilityController],providers: [Availability,{diff --git a/backend/src/infrastructure/availability/scripts/check-health.ts b/backend/src/infrastructure/availability/scripts/check-health.tsnew file mode 100644index 00000000..eef638a5--- /dev/null+++ b/backend/src/infrastructure/availability/scripts/check-health.ts@@ -0,0 +1,19 @@+async function checkHealth(): Promise<void> {+ const url = process.env.SYNC_IN_HEALTHCHECK_URL++ if (!url) {+ throw new Error('SYNC_IN_HEALTHCHECK_URL is not defined')+ }++ const response = await fetch(url, { redirect: 'manual' })++ if (response.status !== 200) {+ throw new Error(`Unexpected HTTP status ${response.status}`)+ }+}++checkHealth().catch((error: unknown) => {+ const message = error instanceof Error ? error.message : String(error)+ console.error(`Health check failed: ${message}`)+ process.exitCode = 1+})diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yamlindex eaba0af4..37c4789a 100644--- a/docker/docker-compose.yaml+++ b/docker/docker-compose.yaml@@ -24,7 +24,8 @@ services:- data:/app/data- desktop_releases:/app/static/releases:rodepends_on:- - mariadb+ mariadb:+ condition: service_healthylogging:driver: json-fileoptions:@@ -41,6 +42,12 @@ services:environment:MYSQL_ROOT_PASSWORD: MySQLRootPasswordMYSQL_DATABASE: sync_in+ healthcheck:+ test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]+ interval: 10s+ timeout: 5s+ retries: 5+ start_period: 30svolumes:- mariadb_data:/var/lib/mysqlnetworks: