Skip to content

Sync-in · Sovereign platform for file storage, sharing, synchronization, and collaboration.

feat(backend:availability): expose health endpoints and add Docker health checks

johaven952681254ec8
diff --git a/Dockerfile b/Dockerfile
index 328b8711..811f16ce 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -23,6 +23,9 @@ ENV NODE_ENV=production
ENV NPM_CONFIG_UPDATE_NOTIFIER=false
ENV PUID=8888
ENV PGID=8888
+ENV SYNC_IN_HEALTHCHECK_URL=http://127.0.0.1:8080/healthz/ready
EXPOSE 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.ts
index 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 const
diff --git a/backend/src/infrastructure/availability/availability.controller.spec.ts b/backend/src/infrastructure/availability/availability.controller.spec.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.md
index 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 and
exposes 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.ts
index 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.ts
new file mode 100644
index 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.yaml
index 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:ro
depends_on:
- - mariadb
+ mariadb:
+ condition: service_healthy
logging:
driver: json-file
options:
@@ -41,6 +42,12 @@ services:
environment:
MYSQL_ROOT_PASSWORD: MySQLRootPassword
MYSQL_DATABASE: sync_in
+ healthcheck:
+ test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
+ interval: 10s
+ timeout: 5s
+ retries: 5
+ start_period: 30s
volumes:
- mariadb_data:/var/lib/mysql
networks: