Project NOMAD is an offline-first knowledge and education server. Wikipedia, thousands of books, courses, maps, and optional local AI, all running on hardware you own with no internet required.
TypeScript
import { DockerService } from '#services/docker_service';
import { SystemService } from '#services/system_service'
import { SystemUpdateService } from '#services/system_update_service'
import { ContainerRegistryService } from '#services/container_registry_service'
import { AutoUpdateService } from '#services/auto_update_service'
import { AppAutoUpdateService } from '#services/app_auto_update_service'
import { ContentAutoUpdateService } from '#services/content_auto_update_service'
import { DownloadService } from '#services/download_service'
import { QueueService } from '#services/queue_service'
import { CheckServiceUpdatesJob } from '#jobs/check_service_updates_job'
import {
affectServiceValidator,
checkLatestVersionValidator,
customAppValidator,
deleteCustomAppValidator,
installServiceValidator,
preflightCustomValidator,
preflightValidator,
serviceLogsValidator,
subscribeToReleaseNotesValidator,
uninstallServiceValidator,
updateCustomAppValidator,
updateServiceValidator,
setServiceAutoUpdateValidator,
setServiceCustomUrlValidator,
createLinkTileValidator,
updateLinkTileValidator,
deleteLinkTileValidator,
normalizeCustomUrl,
} from '#validators/system'
import {
DEFAULT_CPUS,
DEFAULT_MEMORY_MB,
evaluateCustomApp,
} from '#services/custom_app_guard'
import { DEFAULT_LINK_TILE_ICON, isLinkTileIcon } from '../../constants/link_tile_icons.js'
import { inject } from '@adonisjs/core'
import type { HttpContext } from '@adonisjs/core/http'
import logger from '@adonisjs/core/services/logger'
import Service from '#models/service'
import { DEFAULT_LINK_TILE_COLOR } from '../../constants/link_tile_colors.js'
@inject()
export default class SystemController {
constructor(
private systemService: SystemService,
private dockerService: DockerService,
private systemUpdateService: SystemUpdateService,
private containerRegistryService: ContainerRegistryService
) { }
async getInternetStatus({ }: HttpContext) {
return await this.systemService.getInternetStatus();
}
async getSystemInfo({ }: HttpContext) {
return await this.systemService.getSystemInfo();
}
async getServices({ }: HttpContext) {
return await this.systemService.getServices({ installedOnly: true });
}
async installService({ request, response }: HttpContext) {
const payload = await request.validateUsing(installServiceValidator);
const result = await this.dockerService.createContainerPreflight(payload.service_name);
if (result.success) {
response.send({ success: true, message: result.message });
} else {
response.status(400).send({ success: false, message: result.message });
}
}
async affectService({ request, response }: HttpContext) {
const payload = await request.validateUsing(affectServiceValidator);
const result = await this.dockerService.affectContainer(payload.service_name, payload.action);
if (!result) {
response.internalServerError({ error: 'Failed to affect service' });
return;
}
response.send({ success: result.success, message: result.message });
}
async checkLatestVersion({ request }: HttpContext) {
const payload = await request.validateUsing(checkLatestVersionValidator)
return await this.systemService.checkLatestVersion(payload.force);
}
async forceReinstallService({ request, response }: HttpContext) {
const payload = await request.validateUsing(installServiceValidator);
const result = await this.dockerService.forceReinstall(payload.service_name);
if (!result) {
response.internalServerError({ error: 'Failed to force reinstall service' });
return;
}
response.send({ success: result.success, message: result.message });
}
async requestSystemUpdate({ response }: HttpContext) {
if (!this.systemUpdateService.isSidecarAvailable()) {
response.status(503).send({
success: false,
error: 'Update sidecar is not available. Ensure the updater container is running.',
});
return;
}
const result = await this.systemUpdateService.requestUpdate();
if (result.success) {
response.send({
success: true,
message: result.message,
note: 'Monitor update progress via GET /api/system/update/status. The connection may drop during container restart.',
});
} else {
response.status(409).send({
success: false,
error: result.message,
});
}
}
async getSystemUpdateStatus({ response }: HttpContext) {
const status = this.systemUpdateService.getUpdateStatus();
if (!status) {
response.status(500).send({
error: 'Failed to retrieve update status',
});
return;
}
response.send(status);
}
async getSystemUpdateLogs({ response }: HttpContext) {
const logs = this.systemUpdateService.getUpdateLogs();
response.send({ logs });
}
async getAutoUpdateStatus({ response }: HttpContext) {
// Construct inline reusing already-injected singletons + the QueueService
// singleton (its constructor is private to prevent Redis connection leaks,
// so we must not let the container new a fresh one).
const autoUpdateService = new AutoUpdateService(
this.dockerService,
new DownloadService(QueueService.getInstance()),
this.systemService,
this.systemUpdateService,
this.containerRegistryService
)
try {
const status = await autoUpdateService.getStatus()
response.send(status)
} catch (error) {
logger.error({ err: error }, '[SystemController] Failed to get auto-update status')
response.status(500).send({ error: 'Failed to retrieve auto-update status' })
}
}
async getAppAutoUpdateStatus({ response }: HttpContext) {
// Constructed inline reusing already-injected singletons + the QueueService
// singleton (its constructor is private to prevent Redis connection leaks),
// mirroring getAutoUpdateStatus. Apps need no SystemUpdateService (no sidecar).
const appAutoUpdateService = new AppAutoUpdateService(
this.dockerService,
new DownloadService(QueueService.getInstance()),
this.systemService,
this.containerRegistryService
)
try {
const status = await appAutoUpdateService.getStatus()
response.send(status)
} catch (error) {
logger.error({ err: error }, '[SystemController] Failed to get app auto-update status')
response.status(500).send({ error: 'Failed to retrieve app auto-update status' })
}
}
async getContentAutoUpdateStatus({ response }: HttpContext) {
// Mirrors getAppAutoUpdateStatus. Content auto-update needs only the
// DownloadService (for the active-download pre-flight); the catalog and
// collection-update services default-construct inside the service.
const contentAutoUpdateService = new ContentAutoUpdateService(
new DownloadService(QueueService.getInstance())
)
try {
const status = await contentAutoUpdateService.getStatus()
response.send(status)
} catch (error) {
logger.error({ err: error }, '[SystemController] Failed to get content auto-update status')
response.status(500).send({ error: 'Failed to retrieve content auto-update status' })
}
}
async setServiceAutoUpdate({ request, response }: HttpContext) {
const payload = await request.validateUsing(setServiceAutoUpdateValidator)
const service = await Service.query().where('service_name', payload.service_name).first()
if (!service) {
return response.status(404).send({ error: `Service ${payload.service_name} not found` })
}
service.auto_update_enabled = payload.enabled
// Re-enabling clears any prior self-disable so the app gets a fresh start.
if (payload.enabled) {
service.auto_update_consecutive_failures = 0
service.auto_update_disabled_reason = null
}
await service.save()
return response.send({ success: true, message: 'App auto-update preference updated' })
}
async subscribeToReleaseNotes({ request }: HttpContext) {
const reqData = await request.validateUsing(subscribeToReleaseNotesValidator);
return await this.systemService.subscribeToReleaseNotes(reqData.email);
}
async getDebugInfo({}: HttpContext) {
const debugInfo = await this.systemService.getDebugInfo()
return { debugInfo }
}
async checkServiceUpdates({ response }: HttpContext) {
await CheckServiceUpdatesJob.dispatch()
response.send({ success: true, message: 'Service update check dispatched' })
}
async getAvailableVersions({ params, response }: HttpContext) {
const serviceName = params.name
const service = await (await import('#models/service')).default
.query()
.where('service_name', serviceName)
.where('installed', true)
.first()
if (!service) {
return response.status(404).send({ error: `Service ${serviceName} not found or not installed` })
}
try {
const hostArch = await this.getHostArch()
const updates = await this.containerRegistryService.getAvailableUpdates(
service.container_image,
hostArch,
service.source_repo
)
response.send({ versions: updates })
} catch (error) {
logger.error({ err: error }, `[SystemController] Failed to fetch versions for ${serviceName}`)
response.status(500).send({ error: 'Failed to fetch available versions for this service.' })
}
}
async updateService({ request, response }: HttpContext) {
const payload = await request.validateUsing(updateServiceValidator)
const result = await this.dockerService.updateContainer(
payload.service_name,
payload.target_version
)
if (result.success) {
response.send({ success: true, message: result.message })
} else {
response.status(400).send({ error: result.message })
}
}
private async getHostArch(): Promise<string> {
try {
const info = await this.dockerService.docker.info()
const arch = info.Architecture || ''
const archMap: Record<string, string> = {
x86_64: 'amd64',
aarch64: 'arm64',
armv7l: 'arm',
amd64: 'amd64',
arm64: 'arm64',
}
return archMap[arch] || arch.toLowerCase()
} catch {
return 'amd64'
}
}
/**
* Pre-install preflight check: reports port conflicts and resource warnings for a service.
* Results are advisory — the UI shows warnings but allows the user to force-proceed.
*/
async preflightCheck({ request, response }: HttpContext) {
const payload = await request.validateUsing(preflightValidator)
const service = await Service.query().where('service_name', payload.service_name).first()
if (!service) {
return response.status(404).send({ error: `Service ${payload.service_name} not found` })
}
// Extract host ports from container_config — the MySQL driver may return JSON columns
// as an already-parsed object rather than a string, so guard before calling JSON.parse.
const rawConfig = service.container_config
const config = rawConfig
? typeof rawConfig === 'object'
? rawConfig
: JSON.parse(rawConfig as string)
: null
const portBindings: Record<string, [{ HostPort: string }]> =
config?.HostConfig?.PortBindings ?? {}
const hostPorts = Object.values(portBindings)
.flat()
.map((b) => parseInt(b.HostPort, 10))
.filter((p) => !isNaN(p))
// Parse resource requirements from metadata (same object-guard as container_config)
let minMemoryMB = 256
let minDiskMB = 512
try {
const rawMeta = service.metadata
const meta = rawMeta
? typeof rawMeta === 'object'
? rawMeta
: JSON.parse(rawMeta as string)
: null
if (meta?.minMemoryMB) minMemoryMB = meta.minMemoryMB
if (meta?.minDiskMB) minDiskMB = meta.minDiskMB
} catch {}
const [{ conflicts: portConflicts }, resourceWarnings] = await Promise.all([
this.dockerService.checkPortConflicts(hostPorts),
this.systemService.checkResourceWarnings(minMemoryMB, minDiskMB),
])
return response.send({ portConflicts, resourceWarnings })
}
/** Return the next suggested host port for a custom app (8600+ range). */
async suggestCustomPort({ response }: HttpContext) {
const port = await this.systemService.getNextSuggestedCustomPort()
return response.send({ port })
}
/**
* Service-less preflight for the custom-app form: given host ports, volumes and an image,
* report port conflicts, host resource warnings, overridable guard warnings (risky bind
* mounts / untrusted or moving-tag images), and hard blocks (docker socket, system dirs,
* malformed image). Lets the form give live feedback before a Service record exists.
*/
async preflightCustomApp({ request, response }: HttpContext) {
const payload = await request.validateUsing(preflightCustomValidator)
const [{ conflicts }, resourceWarnings] = await Promise.all([
this.dockerService.checkPortConflicts(payload.ports ?? []),
this.systemService.checkResourceWarnings(256, 512),
])
// When editing, the app's own container legitimately holds its ports — don't flag those.
const portConflicts = payload.exclude_service
? conflicts.filter((c) => c.usedBy !== payload.exclude_service)
: conflicts
const guard = evaluateCustomApp({ image: payload.image, volumes: payload.volumes })
return response.send({
portConflicts,
resourceWarnings: [...resourceWarnings, ...guard.warnings],
blocked: guard.blocked,
})
}
/** Create and immediately begin installing a custom app container. */
async createCustomApp({ request, response }: HttpContext) {
const payload = await request.validateUsing(customAppValidator)
// Derive a stable service_name from the friendly name
const slug = payload.friendly_name
.toLowerCase()
.replace(/[^a-z0-9]+/g, '_')
.replace(/^_+|_+$/g, '')
const serviceName = `nomad_custom_${slug}`
const existing = await Service.query().where('service_name', serviceName).first()
if (existing) {
return response.status(409).send({
success: false,
message: `A custom app named "${payload.friendly_name}" already exists. Choose a different name.`,
})
}
// Reject duplicate host ports within the request — Docker would otherwise fail at
// start time with an opaque "port is already allocated" error.
const hostPorts = (payload.ports ?? []).map((p) => p.host)
const duplicateHostPorts = [...new Set(hostPorts.filter((p, i) => hostPorts.indexOf(p) !== i))]
if (duplicateHostPorts.length) {
return response.status(422).send({
success: false,
message: `Duplicate host port(s): ${duplicateHostPorts.join(', ')}. Each host port can map to only one container.`,
})
}
// Security guardrails: hard-block dangerous bind mounts / malformed images regardless of
// force; surface overridable warnings (risky paths, untrusted/moving-tag images) unless forced.
const guard = evaluateCustomApp({ image: payload.image, volumes: payload.volumes })
if (guard.blocked.length) {
return response.status(422).send({
success: false,
message: guard.blocked.join(' '),
blocked: guard.blocked,
})
}
if (!payload.force && guard.warnings.length) {
return response.status(409).send({
success: false,
message: guard.warnings.join(' '),
warnings: guard.warnings,
})
}
// Advisory preflight: surface port conflicts before creating the record so a failed
// install doesn't leave a phantom card. The user can re-submit with force=true to override.
if (!payload.force && hostPorts.length) {
const { conflicts } = await this.dockerService.checkPortConflicts(hostPorts)
if (conflicts.length) {
return response.status(409).send({
success: false,
message: `Port conflict: ${conflicts
.map((c) => `${c.port} (in use by ${c.usedBy})`)
.join(', ')}.`,
portConflicts: conflicts,
})
}
}
const { containerConfig, uiLocation } = this.buildCustomContainerConfig(payload)
await Service.create({
service_name: serviceName,
friendly_name: payload.friendly_name,
container_image: payload.image,
container_config: JSON.stringify(containerConfig),
ui_location: uiLocation,
icon: payload.icon || 'IconBrandDocker',
installed: false,
installation_status: 'idle',
is_dependency_service: false,
is_custom: true,
category: payload.category ?? 'custom',
depends_on: null,
})
const result = await this.dockerService.createContainerPreflight(serviceName)
if (result.success) {
return response.send({ success: true, message: result.message, service_name: serviceName })
}
return response.status(400).send({ success: false, message: result.message })
}
/** Delete a custom app: stop + remove its container, then delete the DB record. */
async deleteCustomApp({ request, response }: HttpContext) {
const payload = await request.validateUsing(deleteCustomAppValidator)
const service = await Service.query().where('service_name', payload.service_name).first()
if (!service) {
return response.status(404).send({ error: `Service ${payload.service_name} not found` })
}
if (!service.is_custom) {
return response.status(403).send({ error: 'Only custom apps can be deleted.' })
}
await this.dockerService.removeCustomAppContainer(payload.service_name, payload.remove_image ?? false)
await service.delete()
return response.send({ success: true, message: `Custom app ${payload.service_name} deleted` })
}
/** Uninstall a curated catalog app: stop + remove its container (optionally its image) and
* return the card to the available catalog. App data under the storage path stays on disk,
* so a later reinstall picks it back up. Custom apps are removed via deleteCustomApp instead,
* which also drops their DB record. */
async uninstallService({ request, response }: HttpContext) {
const payload = await request.validateUsing(uninstallServiceValidator)
const service = await Service.query().where('service_name', payload.service_name).first()
if (!service) {
return response.status(404).send({ error: `Service ${payload.service_name} not found` })
}
if (service.is_custom) {
return response.status(403).send({ error: 'Custom apps are removed via delete.' })
}
if (service.is_dependency_service) {
return response.status(403).send({ error: 'Dependency services cannot be uninstalled directly.' })
}
if (!service.installed) {
return response.status(409).send({ error: `Service ${payload.service_name} is not installed` })
}
const result = await this.dockerService.uninstallService(
payload.service_name,
payload.remove_image ?? false
)
if (!result.success) {
return response.status(500).send({ success: false, message: result.message })
}
return response.send({ success: true, message: result.message })
}
/** Set or clear an app's custom launch URL (works for curated and custom apps). Purely a
* metadata change — no container is touched. An empty/invalid value clears the override, after
* which the default host + port link is used again. */
async setServiceCustomUrl({ request, response }: HttpContext) {
const payload = await request.validateUsing(setServiceCustomUrlValidator)
const service = await Service.query().where('service_name', payload.service_name).first()
if (!service) {
return response.status(404).send({ success: false, message: `Service ${payload.service_name} not found` })
}
// Hidden dependency services (e.g. Qdrant) aren't user-launchable, so they have no link to set.
if (service.is_dependency_service) {
return response.status(403).send({ success: false, message: 'This service cannot be configured.' })
}
// Reject a non-empty value that isn't a valid http(s) URL; an empty value clears the override.
const normalized = normalizeCustomUrl(payload.custom_url)
if (payload.custom_url && payload.custom_url.trim() && !normalized) {
return response.status(422).send({
success: false,
message: 'Custom URL must be a valid http(s) address (e.g. https://jellyfin.myhomelab.net).',
})
}
service.custom_url = normalized
await service.save()
return response.send({ success: true, custom_url: service.custom_url })
}
/**
* Create a dashboard link tile: a shortcut to something the user already runs.
*
* Stored as a service row with no container behind it. `installed` is true so
* the dashboard renders it, `custom_url` carries the destination (getServiceLink
* already prefers custom_url over a computed link), and `is_link_tile` marks it
* so the UI never offers Start/Stop/Update/Uninstall for something with no
* lifecycle. `is_custom` stays false: that flag means a container NOMAD installs.
*/
async createLinkTile({ request, response }: HttpContext) {
const payload = await request.validateUsing(createLinkTileValidator)
const normalized = normalizeCustomUrl(payload.url)
if (!normalized) {
return response.status(422).send({
success: false,
message: 'Enter a valid URL, for example 192.168.1.50:8080 or https://nas.local.',
})
}
if (payload.icon && !isLinkTileIcon(payload.icon)) {
return response.status(422).send({ success: false, message: 'Unknown icon.' })
}
// Namespaced so a tile can never collide with a curated catalog entry. The
// seeder only ever touches names in its own DEFAULT_SERVICES list, so a
// `nomad_link_` row is invisible to a reseed.
const slug = payload.friendly_name
.toLowerCase()
.replace(/[^a-z0-9]+/g, '_')
.replace(/^_+|_+$/g, '')
if (!slug) {
return response.status(422).send({ success: false, message: 'Enter a name using letters or numbers.' })
}
const serviceName = `nomad_link_${slug}`
const existing = await Service.query().where('service_name', serviceName).first()
if (existing) {
return response.status(409).send({
success: false,
message: `A link named "${payload.friendly_name}" already exists. Choose a different name.`,
})
}
const service = await Service.create({
service_name: serviceName,
container_image: '',
container_config: null,
friendly_name: payload.friendly_name,
description: payload.description ?? null,
icon: payload.icon || DEFAULT_LINK_TILE_ICON,
display_order: payload.display_order ?? 90,
installed: true,
installation_status: 'idle',
is_dependency_service: false,
ui_location: null,
custom_url: normalized,
is_custom: false,
is_user_modified: true,
is_link_tile: true,
link_color: payload.link_color ?? DEFAULT_LINK_TILE_COLOR,
category: 'Links',
})
return response.status(201).send({ success: true, service_name: service.service_name })
}
/** Reconfigure an existing link tile. service_name is immutable so the tile keeps its identity. */
async updateLinkTile({ request, response }: HttpContext) {
const payload = await request.validateUsing(updateLinkTileValidator)
const service = await Service.query().where('service_name', payload.service_name).first()
if (!service) {
return response.status(404).send({ success: false, message: 'Link not found' })
}
if (!service.is_link_tile) {
return response.status(403).send({ success: false, message: 'That app is not a link.' })
}
const normalized = normalizeCustomUrl(payload.url)
if (!normalized) {
return response.status(422).send({
success: false,
message: 'Enter a valid URL, for example 192.168.1.50:8080 or https://nas.local.',
})
}
if (payload.icon && !isLinkTileIcon(payload.icon)) {
return response.status(422).send({ success: false, message: 'Unknown icon.' })
}
service.friendly_name = payload.friendly_name
service.description = payload.description ?? null
service.icon = payload.icon || DEFAULT_LINK_TILE_ICON
service.display_order = payload.display_order ?? service.display_order ?? 90
service.custom_url = normalized
service.link_color = payload.link_color ?? service.link_color ?? DEFAULT_LINK_TILE_COLOR
await service.save()
return response.send({ success: true })
}
/** Remove a link tile. Nothing to uninstall: there is no container, image or volume. */
async deleteLinkTile({ request, response }: HttpContext) {
const payload = await request.validateUsing(deleteLinkTileValidator)
const service = await Service.query().where('service_name', payload.service_name).first()
if (!service) {
return response.status(404).send({ success: false, message: 'Link not found' })
}
if (!service.is_link_tile) {
return response.status(403).send({ success: false, message: 'That app is not a link.' })
}
await service.delete()
return response.send({ success: true })
}
/** Re-pull a custom app's image and recreate its container in place (preserving volumes). */
async updateCustomApp_pullLatest({ request, response }: HttpContext) {
const payload = await request.validateUsing(installServiceValidator)
const service = await Service.query().where('service_name', payload.service_name).first()
if (!service) {
return response.status(404).send({ success: false, message: `Service ${payload.service_name} not found` })
}
if (!service.is_custom) {
return response.status(403).send({ success: false, message: 'Only custom apps can be updated this way.' })
}
const result = await this.dockerService.recreateCustomAppContainer(payload.service_name, {
forcePull: true,
})
if (result.success) {
return response.send({ success: true, message: result.message })
}
return response.status(400).send({ success: false, message: result.message })
}
/** Return the last N lines of a service container's logs. */
async getServiceLogs({ params, request, response }: HttpContext) {
// Scope to managed services only — otherwise any sibling container's logs (admin app,
// database) would be readable by name on this unauthenticated API surface.
const service = await Service.query().where('service_name', params.name).first()
if (!service) {
return response.status(404).send({ success: false, message: `Service ${params.name} not found` })
}
const { tail } = await request.validateUsing(serviceLogsValidator)
const result = await this.dockerService.getContainerLogs(params.name, tail ?? 200)
if (!result.success) {
return response.status(404).send({ success: false, message: result.message })
}
return response.send({ success: true, logs: result.logs })
}
/** Return a one-shot CPU/memory usage snapshot for a running service container. */
async getServiceStats({ params, response }: HttpContext) {
// Scope to managed services only (see getServiceLogs).
const service = await Service.query().where('service_name', params.name).first()
if (!service) {
return response.status(404).send({ success: false, message: `Service ${params.name} not found` })
}
const result = await this.dockerService.getContainerStats(params.name)
if (!result.success) {
return response.status(404).send({ success: false, message: result.message })
}
return response.send({ success: true, running: result.running ?? false, stats: result.stats ?? null })
}
/** Return an app's current configuration in the editable form-shape. */
async getCustomApp({ params, response }: HttpContext) {
const service = await Service.query().where('service_name', params.name).first()
if (!service) {
return response.status(404).send({ error: `Service ${params.name} not found` })
}
// Custom and curated apps are both editable; hidden dependency services (e.g. Qdrant) are not.
if (service.is_dependency_service) {
return response.status(403).send({ error: 'This service cannot be edited.' })
}
return response.send({ success: true, app: this.parseCustomContainerConfig(service) })
}
/** Reconfigure an app: validate + guard, persist the new config, then recreate the container.
* Works for both custom apps and curated (pre-configured) apps. Editing a curated app marks it
* user-modified so the seeder stops overwriting the user's changes. */
async updateCustomApp({ request, response }: HttpContext) {
const payload = await request.validateUsing(updateCustomAppValidator)
const service = await Service.query().where('service_name', payload.service_name).first()
if (!service) {
return response.status(404).send({ success: false, message: `Service ${payload.service_name} not found` })
}
// Custom and curated apps are both editable; hidden dependency services (e.g. Qdrant) are not.
if (service.is_dependency_service) {
return response.status(403).send({ success: false, message: 'This service cannot be edited.' })
}
// Reject duplicate host ports within the request.
const hostPorts = (payload.ports ?? []).map((p) => p.host)
const duplicateHostPorts = [...new Set(hostPorts.filter((p, i) => hostPorts.indexOf(p) !== i))]
if (duplicateHostPorts.length) {
return response.status(422).send({
success: false,
message: `Duplicate host port(s): ${duplicateHostPorts.join(', ')}. Each host port can map to only one container.`,
})
}
// Security guardrails (same posture as create).
const guard = evaluateCustomApp({ image: payload.image, volumes: payload.volumes })
if (guard.blocked.length) {
return response.status(422).send({ success: false, message: guard.blocked.join(' '), blocked: guard.blocked })
}
if (!payload.force && guard.warnings.length) {
return response.status(409).send({ success: false, message: guard.warnings.join(' '), warnings: guard.warnings })
}
// Port conflicts — but ignore ports already held by this app's own container.
if (!payload.force && hostPorts.length) {
const { conflicts } = await this.dockerService.checkPortConflicts(hostPorts)
const external = conflicts.filter((c) => c.usedBy !== payload.service_name)
if (external.length) {
return response.status(409).send({
success: false,
message: `Port conflict: ${external
.map((c) => `${c.port} (in use by ${c.usedBy})`)
.join(', ')}.`,
portConflicts: external,
})
}
}
// Merge the form fields into the app's existing config rather than rebuilding from scratch,
// so advanced settings a curated app ships with (GPU device requests, special env, etc.) are
// preserved across an edit.
// Preserve an explicit scheme (e.g. ui_location "https:8480") across an edit — otherwise a
// TLS-serving app's Open link would silently revert to http after any reconfigure.
const prevScheme = (service.ui_location || '').match(/^(https?):\d+$/)?.[1]
const { containerConfig, uiLocation } = this.mergeCustomContainerConfig(
service.container_config,
payload
)
service.friendly_name = payload.friendly_name
service.container_image = payload.image
service.container_config = JSON.stringify(containerConfig)
service.ui_location = prevScheme && uiLocation && /^\d+$/.test(uiLocation)
? `${prevScheme}:${uiLocation}`
: uiLocation
service.category = payload.category ?? service.category ?? 'custom'
if (payload.icon) service.icon = payload.icon
// Flag as user-modified so the seeder stops overwriting this app's config on future runs.
service.is_user_modified = true
await service.save()
const result = await this.dockerService.recreateCustomAppContainer(payload.service_name)
if (result.success) {
return response.send({ success: true, message: result.message, service_name: payload.service_name })
}
return response.status(400).send({ success: false, message: result.message })
}
/**
* Build a Docker container config (HostConfig + ExposedPorts + Env) from custom-app form input,
* applying default resource caps. Shared by create and update so both stay in lockstep.
*/
private buildCustomContainerConfig(payload: {
ports?: { container: number; host: number }[]
volumes?: { host_path: string; container_path: string }[]
env?: string[]
memory_mb?: number
cpus?: number
}): { containerConfig: Record<string, any>; uiLocation: string | null } {
const portBindings: Record<string, [{ HostPort: string }]> = {}
const exposedPorts: Record<string, {}> = {}
for (const { container, host } of payload.ports ?? []) {
portBindings[`${container}/tcp`] = [{ HostPort: String(host) }]
exposedPorts[`${container}/tcp`] = {}
}
const binds = (payload.volumes ?? []).map(
({ host_path, container_path }) => `${host_path}:${container_path}`
)
// Resource caps so a runaway custom container can't starve the host. Memory is bytes;
// NanoCpus is CPUs × 1e9. Defaults are generous and user-overridable.
const memoryBytes = (payload.memory_mb ?? DEFAULT_MEMORY_MB) * 1024 * 1024
const nanoCpus = Math.round((payload.cpus ?? DEFAULT_CPUS) * 1e9)
const containerConfig: Record<string, any> = {
HostConfig: {
RestartPolicy: { Name: 'unless-stopped' },
PortBindings: portBindings,
Memory: memoryBytes,
NanoCpus: nanoCpus,
...(binds.length ? { Binds: binds } : {}),
},
ExposedPorts: exposedPorts,
...(payload.env?.length ? { Env: payload.env } : {}),
}
const firstHostPort = payload.ports?.[0]?.host
const uiLocation = firstHostPort ? String(firstHostPort) : null
return { containerConfig, uiLocation }
}
/**
* Merge custom-app form input into an app's *existing* container config. Used by the edit path so
* editing a curated app only changes the fields exposed in the form (image/ports/volumes/env and,
* if supplied, resource caps) while preserving everything else it ships with (GPU DeviceRequests,
* User, custom HostConfig keys, etc.). Unlike buildCustomContainerConfig, resource caps are NOT
* defaulted here — a curated app intentionally left uncapped stays uncapped unless the user sets one.
*/
private mergeCustomContainerConfig(
existingRaw: string | null,
payload: {
ports?: { container: number; host: number }[]
volumes?: { host_path: string; container_path: string }[]
env?: string[]
memory_mb?: number
cpus?: number
}
): { containerConfig: Record<string, any>; uiLocation: string | null } {
const parsed = existingRaw
? typeof existingRaw === 'object'
? existingRaw
: JSON.parse(existingRaw as string)
: {}
// Deep clone so we never mutate the parsed source.
const containerConfig: Record<string, any> = JSON.parse(JSON.stringify(parsed ?? {}))
containerConfig.HostConfig = containerConfig.HostConfig ?? {}
// Keep a restart policy if the existing config lacked one.
containerConfig.HostConfig.RestartPolicy =
containerConfig.HostConfig.RestartPolicy ?? { Name: 'unless-stopped' }
const portBindings: Record<string, [{ HostPort: string }]> = {}
const exposedPorts: Record<string, {}> = {}
for (const { container, host } of payload.ports ?? []) {
portBindings[`${container}/tcp`] = [{ HostPort: String(host) }]
exposedPorts[`${container}/tcp`] = {}
}
containerConfig.HostConfig.PortBindings = portBindings
containerConfig.ExposedPorts = exposedPorts
const binds = (payload.volumes ?? []).map(
({ host_path, container_path }) => `${host_path}:${container_path}`
)
if (binds.length) containerConfig.HostConfig.Binds = binds
else delete containerConfig.HostConfig.Binds
if (payload.env?.length) containerConfig.Env = payload.env
else delete containerConfig.Env
// Only touch resource caps when the user explicitly set them — preserve existing/uncapped otherwise.
if (payload.memory_mb != null) {
containerConfig.HostConfig.Memory = payload.memory_mb * 1024 * 1024
}
if (payload.cpus != null) {
containerConfig.HostConfig.NanoCpus = Math.round(payload.cpus * 1e9)
}
const firstHostPort = payload.ports?.[0]?.host
const uiLocation = firstHostPort ? String(firstHostPort) : null
return { containerConfig, uiLocation }
}
/** Inverse of buildCustomContainerConfig: turn a stored Service into the editable form-shape. */
private parseCustomContainerConfig(service: Service) {
const raw = service.container_config
const config = raw ? (typeof raw === 'object' ? raw : JSON.parse(raw as string)) : {}
const hostConfig = config?.HostConfig ?? {}
const ports = Object.entries(hostConfig.PortBindings ?? {}).map(([key, val]: [string, any]) => ({
container: Number.parseInt(key, 10),
host: Number.parseInt(val?.[0]?.HostPort, 10),
}))
const volumes = (hostConfig.Binds ?? []).map((bind: string) => {
const idx = bind.indexOf(':')
return { host_path: bind.slice(0, idx), container_path: bind.slice(idx + 1) }
})
return {
service_name: service.service_name,
friendly_name: service.friendly_name,
image: service.container_image,
category: service.category ?? 'custom',
icon: service.icon ?? 'IconBrandDocker',
ports,
volumes,
env: (config?.Env ?? []) as string[],
memory_mb: hostConfig.Memory ? Math.round(hostConfig.Memory / (1024 * 1024)) : undefined,
cpus: hostConfig.NanoCpus ? hostConfig.NanoCpus / 1e9 : undefined,
}
}
}