Class: ContainerSettingOptions
The settings of a container: given to Docker.createContainer and DockerImage.run() (create, then start), which use the image's defaults (command, environment…) for the settings absent, and to DockerContainer.update(), which changes the settings given and keeps the others: the limits and the restart policy live, the others by recreating the container. Every option is optional.
Example
import {Docker, ContainerCapability} from 'lakutata/com/docker'
declare const docker: Docker
const image = await docker.pullImage({repo: 'nginx', tag: '1.27'})
const container = await image.run({
name: 'web',
env: {TZ: 'UTC'},
memoryLimit: 256 * 1024 * 1024,
restartPolicy: 'unless-stopped',
ports: [{port: 80, type: 'tcp', hostPorts: [8080]}],
binds: [{hostPath: '/srv/web/html', containerPath: '/usr/share/nginx/html', rw: false}],
networks: [{networkName: 'front'}],
capabilities: [ContainerCapability.NET_ADMIN]
})
//The same container, with 512 MiB of memory, restarted 3 times at most when it fails
await container.update({memoryLimit: 512 * 1024 * 1024, restartPolicy: 'on-failure:3'})Extends
Indexable
[
prop:string|symbol]:any
Constructors
Constructor
new ContainerSettingOptions(
props?):ContainerSettingOptions
Create a DTO from its data, validated against the class schema: the defaults applied, the keys without schema removed (unless the class has an @IndexSignature). The instance then validates each change of a property, or of a value nested in it (an array, an object): an invalid change throws an InvalidValueException and is undone.
Parameters
props?
Record<string, any>
The data of the DTO. Default: no data ({}).
Returns
ContainerSettingOptions
Throws
When the data does not match the class schema.
Inherited from
Properties
binds?
optionalbinds?:ContainerBind[]
The host files and directories mounted into the container (docker run -v), each one required to have its hostPath, its containerPath and rw (false for read-only); sent to Docker as "hostPath:containerPath:rw" or "hostPath:containerPath:ro".
capabilities?
optionalcapabilities?:ContainerCapability[]
The Linux capabilities added to Docker's default set (docker run --cap-add); a value outside ContainerCapability fails the validation. None added when absent (update() keeps the container's).
cgroup?
optionalcgroup?:string
The cgroup the container runs in (the Docker Engine's HostConfig.Cgroup): 'container:<name|id>' shares another container's cgroup; its own when absent.
cgroupParent?
optionalcgroupParent?:string
The parent cgroup the container's cgroup is created under (docker run --cgroup-parent); a relative path is relative to the cgroup of the init process. The cgroups are created when missing.
cmd?
optionalcmd?:string[]
The command, replacing the image's CMD: the executable followed by its arguments (['node', 'server.js']), an array only.
cpuSet?
optionalcpuSet?:number[]
The indexes of the host CPUs the container may run on ([0, 1], sent to Docker as "0,1"); all of them when absent. Each one is an integer.
devices?
optionaldevices?: (Pick<ContainerDevice,"hostPath"|"containerPath"> &Partial<Pick<ContainerDevice,"cgroupPermissions">>)[]
The host devices made available in the container (docker run --device), each one required to have its hostPath and its containerPath; its cgroupPermissions, a combination of r, w and m, is 'rwm' by default.
entrypoint?
optionalentrypoint?:string[]
The entry point, replacing the image's ENTRYPOINT: the executable followed by its arguments, an array only. [''] removes the image's entry point: the command runs alone.
env?
optionalenv?:Record<string,string>
The environment variables, by name ({NODE_ENV: 'production'}), added to the image's ones; the values are strings.
hostname?
optionalhostname?:string
The host name seen in the container; Docker uses the first 12 characters of the container ID when absent.
memoryLimit?
optionalmemoryLimit?:number
The memory limit, in bytes (256 * 1024 * 1024 for 256 MiB); Docker requires at least 6 MiB. 0 or absent for no limit. The swap limit is Docker's default: as much swap as memory.
Default
0name?
optionalname?:string
The container name, unique on the Docker host: letters, digits, _, . and -, starting with a letter or a digit. Docker generates one (happy_turing) when absent.
networks?
optionalnetworks?: (Pick<ContainerNetwork,"networkName"> &Partial<Pick<ContainerNetwork,"ip"|"ipv6">>)[]
The networks the container is connected to, each one required to have its networkName; the default bridge network when absent. On a user-defined network, ip (an IPv4 address) and ipv6 (an IPv6 address) set the container's static addresses, within the network's range; empty or absent, Docker allocates them. They are ignored on bridge, host and none.
OOMKillDisable?
optionalOOMKillDisable?:boolean
Keep the kernel's OOM killer from killing the container's processes when it runs out of memory; set it with a memory limit only, or the host may kill its own processes instead.
pidMode?
optionalpidMode?:string
The PID namespace of the container (docker run --pid): 'container:<name|id>' joins another container's, 'host' uses the host's; its own when absent.
ports?
optionalports?: (Pick<ContainerPort,"port"|"type"> &Partial<Pick<ContainerPort,"hostPorts">>)[]
The container ports published on the host (docker run -p), each one required to have a port (a valid port number) and a type ('tcp' or 'udp'), sent to Docker as "80/tcp". Its hostPorts are the host ports forwarded to it, bound on every host address ([8080], each one once); empty, or absent, it is published on no host port.
privileged?
optionalprivileged?:boolean
Run the container privileged (docker run --privileged): every capability and every host device, without the security restrictions. It gives the container full access to the host.
restartPolicy?
optionalrestartPolicy?:ContainerRestartPolicy
When Docker restarts the container after it exits: '', 'no', 'always', 'unless-stopped', 'on-failure' (with no limit on the retries) or 'on-failure:N' (N retries at most, 'on-failure:3'); another value fails the validation. '' or absent for no restart.
tty?
optionaltty?:boolean
Give the container's main process a terminal (docker run -t): its output is then not multiplexed, and DockerContainer.logs() gives it as written.
Methods
Alternatives()
staticAlternatives<TSchema>(...types):AlternativesSchema<TSchema>
Build a schema matching a value against several schemas, in order: the first one matching validates it.
Type Parameters
TSchema
TSchema = any
Parameters
types
...SchemaLike[]
The schemas tried in order.
Returns
AlternativesSchema<TSchema>
A new alternatives schema.
Inherited from
Any()
staticAny<TSchema>():AnySchema<TSchema>
Build a schema accepting any value (undefined included unless marked required()).
Type Parameters
TSchema
TSchema = any
Returns
AnySchema<TSchema>
A new schema.
Inherited from
Array()
staticArray<TSchema>(...types):ArraySchema<TSchema>
Build a schema of arrays whose items match one of the schemas given; strict.
Type Parameters
TSchema
TSchema = any[]
Parameters
types
The schemas an item may match. Default: any item.
Returns
ArraySchema<TSchema>
A new array schema.
Inherited from
AsyncFunction()
staticAsyncFunction<TSchema>():FunctionSchema<TSchema>
Build a schema of async functions (declared async); a function which only returns a promise is rejected.
Type Parameters
TSchema
TSchema = Function
Returns
FunctionSchema<TSchema>
A new function schema.
Inherited from
Attempt()
staticAttempt<TSchema>(value,schema,options?):TSchemaextendsSchema<Value> ?Value:never
Validate a value against a schema and return the validated value. Unlike DTO.validate(), the default options of lakutata are not applied: an unknown key is rejected, not removed.
Type Parameters
TSchema
TSchema extends Schema
Parameters
value
any
The value to validate.
schema
TSchema
The schema to validate against.
options?
The validation options.
Returns
TSchema extends Schema<Value> ? Value : never
The validated value.
Throws
When the value does not match the schema.
Inherited from
BigInt()
staticBigInt<TSchema>():BigIntSchema<TSchema>
Build a schema of bigints; strict: a value of another type is rejected, not converted.
Type Parameters
TSchema
TSchema = bigint
Returns
BigIntSchema<TSchema>
A new bigint schema.
Inherited from
Binary()
staticBinary<TSchema>():BinarySchema<TSchema>
Build a schema of Buffers; strict: a value of another type is rejected, not converted.
Type Parameters
TSchema
TSchema = Buffer<ArrayBufferLike>
Returns
BinarySchema<TSchema>
A new binary schema.
Inherited from
Boolean()
staticBoolean<TSchema>():BooleanSchema<TSchema>
Build a schema of booleans; strict: a value of another type is rejected, not converted (the string 'true' is not a boolean).
Type Parameters
TSchema
TSchema = boolean
Returns
BooleanSchema<TSchema>
A new boolean schema.
Inherited from
Build()
staticBuild<TSchema>(description):Schema<TSchema>
Rebuild a schema from its description (the output of schema.describe()), exactly.
Type Parameters
TSchema
TSchema = any
Parameters
description
Description
The description of the schema.
Returns
Schema<TSchema>
The schema.
Inherited from
Class()
staticClass<TSchema>(inheritsFrom?):FunctionSchema<TSchema>
Build a schema of classes, optionally of the subclasses of a class.
Type Parameters
TSchema
TSchema = Function
Parameters
inheritsFrom?
TSchema | (() => TSchema)
The class the value must be or extend, or a function returning it (for a class declared later). Default: any class.
Returns
FunctionSchema<TSchema>
A new function schema.
Inherited from
Cron()
staticCron<TSchema>(options?):StringSchema<TSchema>
Build a schema of cron expression strings. The options not given default to: seconds allowed (6 fields), ? allowed for a day, 7 accepted as Sunday, no aliases (@daily).
Type Parameters
TSchema
TSchema = string
Parameters
options?
The cron syntax accepted.
Returns
StringSchema<TSchema>
A new string schema.
Inherited from
Date()
staticDate<TSchema>():DateSchema<TSchema>
Build a schema of Date objects; strict: a value of another type is rejected, not converted (a date string or a timestamp is not a date).
Type Parameters
TSchema
TSchema = Date
Returns
DateSchema<TSchema>
A new date schema.
Inherited from
description()
staticdescription(desc): typeofDTO
Set the description of the class schema, written into its JSON Schema and its descriptions. The description is not inherited by the subclasses.
Parameters
desc
string
The description.
Returns
typeof DTO
The class itself, for chaining.
Inherited from
fromJsonSchema()
staticfromJsonSchema<T>(this,schema,options?):T
Create a DTO class (a subclass of the current DTO class) from an object JSON Schema (or an OpenAPI schema object), validating like JSON Schema: its properties become the properties of the DTO, its other keywords (unknown keys, pattern properties, key counts, dependencies, subschemas) constrain the whole object.
Type Parameters
T
T extends typeof DTO
Parameters
this
T
schema
The JSON Schema of an object (or an OpenAPI schema object), or a reference ($ref) to one.
options?
FromJsonSchemaOptions & object
The version of the JSON Schema, where its references are resolved, whether the values are converted, and the name of the class. Default name: the title of the JSON Schema, else the current class name followed by FromJsonSchema.
Returns
T
The new DTO class.
Throws
When the JSON Schema does not describe objects, a reference cannot be resolved, or a pattern is not a valid regular expression.
Inherited from
fromOpenAPI()
staticfromOpenAPI<T>(this,document,options?):Record<string,T>
Create the DTO classes of the object schemas of an OpenAPI document (its components.schemas), by name; the references between the schemas are resolved in the document. The schemas which do not describe objects are skipped.
Type Parameters
T
T extends typeof DTO
Parameters
this
T
document
Record<string, unknown>
The OpenAPI 3.0 or 3.1 document.
options?
Omit<FromJsonSchemaOptions, "document">
How the JSON Schemas are read. Default dialect: the version of the document's openapi field.
Returns
Record<string, T>
The DTO classes, by the names of their schemas.
Throws
When the document has no components.schemas, or a schema cannot be converted.
Inherited from
Function()
staticFunction<TSchema>():FunctionSchema<TSchema>
Build a schema of functions; strict.
Type Parameters
TSchema
TSchema = Function
Returns
FunctionSchema<TSchema>
A new function schema.
Inherited from
Glob()
staticGlob<TSchema>():StringSchema<TSchema>
Build a schema of glob pattern strings (*.ts, src/**).
Type Parameters
TSchema
TSchema = string
Returns
StringSchema<TSchema>
A new string schema.
Inherited from
HttpDocument()
staticHttpDocument<TSchema>():StringSchema<TSchema>
Build a schema of HTML or XML document strings.
Type Parameters
TSchema
TSchema = string
Returns
StringSchema<TSchema>
A new string schema.
Inherited from
In()
staticIn(ref,options?):Reference
Create a reference to an array of the validated object, whose items are the values allowed, for valid() or invalid().
Parameters
ref
string
The path of the referenced array.
options?
How the reference is resolved.
Returns
The reference.
Inherited from
InstanceOf()
staticInstanceOf<TSchema>(constructor):AnySchema<TSchema>
Build a schema of the instances of a class (the instances of its subclasses included).
Type Parameters
TSchema
TSchema = Function
Parameters
constructor
TSchema
The class.
Returns
AnySchema<TSchema>
A new schema.
Inherited from
isValid()
Call Signature
staticisValid<T>(data):boolean
Check whether a value matches a schema (the class schema when none is given), without throwing.
Type Parameters
T
T = any
Parameters
data
T
The value to check.
Returns
boolean
true when the value matches the schema, else false.
Inherited from
Call Signature
staticisValid<T>(data,options):boolean
Check whether a value matches a schema (the class schema when none is given), without throwing.
Type Parameters
T
T = any
Parameters
data
T
The value to check.
options
The validation options, merged with the defaults (unknown keys removed, the first error only).
Returns
boolean
true when the value matches the schema, else false.
Inherited from
Call Signature
staticisValid<T>(data,schema):boolean
Check whether a value matches a schema (the class schema when none is given), without throwing.
Type Parameters
T
T = any
Parameters
data
T
The value to check.
schema
The schema to check against, instead of the class schema.
Returns
boolean
true when the value matches the schema, else false.
Inherited from
Call Signature
staticisValid<T>(data,schema,options):boolean
Check whether a value matches a schema (the class schema when none is given), without throwing.
Type Parameters
T
T = any
Parameters
data
T
The value to check.
schema
The schema to check against, instead of the class schema.
options
The validation options, merged with the defaults (unknown keys removed, the first error only).
Returns
boolean
true when the value matches the schema, else false.
Inherited from
isValidAsync()
Call Signature
staticisValidAsync<T>(data):Promise<boolean>
Check whether a value matches a schema (the class schema when none is given), without throwing; asynchronously, running the external rules of the schema.
Type Parameters
T
T = any
Parameters
data
T
The value to check.
Returns
Promise<boolean>
A promise of true when the value matches the schema, else false.
Inherited from
Call Signature
staticisValidAsync<T>(data,options):Promise<boolean>
Check whether a value matches a schema (the class schema when none is given), without throwing; asynchronously, running the external rules of the schema.
Type Parameters
T
T = any
Parameters
data
T
The value to check.
options
The validation options, merged with the defaults (unknown keys removed, the first error only).
Returns
Promise<boolean>
A promise of true when the value matches the schema, else false.
Inherited from
Call Signature
staticisValidAsync<T>(data,schema):Promise<boolean>
Check whether a value matches a schema (the class schema when none is given), without throwing; asynchronously, running the external rules of the schema.
Type Parameters
T
T = any
Parameters
data
T
The value to check.
schema
The schema to check against, instead of the class schema.
Returns
Promise<boolean>
A promise of true when the value matches the schema, else false.
Inherited from
Call Signature
staticisValidAsync<T>(data,schema,options):Promise<boolean>
Check whether a value matches a schema (the class schema when none is given), without throwing; asynchronously, running the external rules of the schema.
Type Parameters
T
T = any
Parameters
data
T
The value to check.
schema
The schema to check against, instead of the class schema.
options
The validation options, merged with the defaults (unknown keys removed, the first error only).
Returns
Promise<boolean>
A promise of true when the value matches the schema, else false.
Inherited from
Link()
staticLink<TSchema>(ref):LinkSchema<TSchema>
Build a schema linking to another schema of the same tree, for the recursive structures (a tree of nodes): #id for the schema given that id, / for the root, ... for an ancestor.
Type Parameters
TSchema
TSchema extends Schema
Parameters
ref
string
The path of the linked schema.
Returns
LinkSchema<TSchema>
A new link schema.
Inherited from
Number()
staticNumber<TSchema>():NumberSchema<TSchema>
Build a schema of numbers; strict: a value of another type is rejected, not converted (the string '5' is not the number 5).
Type Parameters
TSchema
TSchema = number
Returns
NumberSchema<TSchema>
A new number schema.
Inherited from
Object()
staticObject<TSchema,isStrict,T>(schema?):ObjectSchema<TSchema>
Build a schema of objects, with the schemas of their keys; strict. With the default validation options, the keys without schema are removed.
Type Parameters
TSchema
TSchema = any
isStrict
isStrict = false
T
T = TSchema
Parameters
schema?
SchemaMap<T, isStrict>
The schemas of the keys, by key. Default: no key declared.
Returns
ObjectSchema<TSchema>
A new object schema.
Inherited from
optional()
staticoptional():ObjectSchema
Get the class schema marked as optional: undefined is accepted (as by Schema()).
Returns
A new object schema.
Inherited from
options()
staticoptions(options):ObjectSchema
Get the class schema with its own validation options, which override the options of the validation for the object and its nested values.
Parameters
options
The validation options.
Returns
A new object schema.
Inherited from
Ref()
staticRef(key,options?):Reference
Create a reference to another value of the validated object (a sibling key by default), resolved at validation, for the rules comparing values (DTO.Number().greater(DTO.Ref('min'))).
Parameters
key
string
The path of the referenced value: a key, a.b for a nested key, /key from the root.
options?
How the reference is resolved.
Returns
The reference.
Inherited from
required()
staticrequired():ObjectSchema
Get the class schema marked as required: undefined is rejected.
Returns
A new object schema.
Inherited from
Schema()
staticSchema():ObjectSchema
Get the class schema: an object schema of the properties declared with @Expect (the parents' included), with the @IndexSignature and the description of the class. The schema is optional (it accepts undefined): use required() for a required one.
Returns
The object schema; the same instance until a schema declaration changes.
Inherited from
String()
staticString<TSchema>():StringSchema<TSchema>
Build a schema of strings; strict: a value of another type is rejected, not converted.
Type Parameters
TSchema
TSchema = string
Returns
StringSchema<TSchema>
A new string schema.
Inherited from
Symbol()
staticSymbol<TSchema>():SymbolSchema<TSchema>
Build a schema of symbols; strict.
Type Parameters
TSchema
TSchema = Symbol
Returns
SymbolSchema<TSchema>
A new symbol schema.
Inherited from
toJsonSchema()
statictoJsonSchema(version?,options?):JSONSchema
Convert the class schema to a JSON Schema, for an API document or another validator. What JSON Schema cannot express (custom rules, references to other values) is dropped, so the JSON Schema may accept more values, never less.
Parameters
version?
"draft-2020-12" | "draft-2019-09" | "draft-07" | "draft-04"
The JSON Schema version to write. Default 'draft-2020-12'.
options?
Omit<ToJsonSchemaOptions, "target">
The validation options the schema is used with, whether $schema is written, and the object receiving the shared schemas. Default: no option ({}).
Returns
A new JSON Schema.
Throws
When the version is unknown.
Inherited from
toOpenAPIJsonSchema()
statictoOpenAPIJsonSchema(version?,options?):JSONSchema
Convert the class schema to an OpenAPI schema object, for the components.schemas of an OpenAPI document.
Parameters
version?
"3.0" | "3.1"
The OpenAPI version: '3.0' or '3.1'. Default '3.1'.
options?
Omit<ToJsonSchemaOptions, "target" | "dialect">
The validation options the schema is used with, and the object receiving the shared schemas. Default: no option ({}).
Returns
A new OpenAPI schema object.
Inherited from
validate()
Call Signature
staticvalidate<T>(data):T
Validate a value against a schema (the class schema when none is given).
Type Parameters
T
T = any
Parameters
data
T
The value to check.
Returns
T
The validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).
Throws
When the value does not match the schema (its cause holds the details).
Inherited from
Call Signature
staticvalidate<T>(data,options):T
Validate a value against a schema (the class schema when none is given).
Type Parameters
T
T = any
Parameters
data
T
The value to check.
options
The validation options, merged with the defaults (unknown keys removed, the first error only).
Returns
T
The validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).
Throws
When the value does not match the schema (its cause holds the details).
Inherited from
Call Signature
staticvalidate<T>(data,schema):T
Validate a value against a schema (the class schema when none is given).
Type Parameters
T
T = any
Parameters
data
T
The value to check.
schema
The schema to check against, instead of the class schema.
Returns
T
The validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).
Throws
When the value does not match the schema (its cause holds the details).
Inherited from
Call Signature
staticvalidate<T>(data,schema,options):T
Validate a value against a schema (the class schema when none is given).
Type Parameters
T
T = any
Parameters
data
T
The value to check.
schema
The schema to check against, instead of the class schema.
options
The validation options, merged with the defaults (unknown keys removed, the first error only).
Returns
T
The validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).
Throws
When the value does not match the schema (its cause holds the details).
Inherited from
validateAsync()
Call Signature
staticvalidateAsync<T>(data):Promise<T>
Validate a value against a schema (the class schema when none is given), asynchronously: the external rules of the schema (.external()) run, which the synchronous validation cannot run.
Type Parameters
T
T = any
Parameters
data
T
The value to check.
Returns
Promise<T>
A promise of the validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).
Throws
When the value does not match the schema (the promise rejects; its cause holds the details).
Inherited from
Call Signature
staticvalidateAsync<T>(data,options):Promise<T>
Validate a value against a schema (the class schema when none is given), asynchronously: the external rules of the schema (.external()) run, which the synchronous validation cannot run.
Type Parameters
T
T = any
Parameters
data
T
The value to check.
options
The validation options, merged with the defaults (unknown keys removed, the first error only).
Returns
Promise<T>
A promise of the validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).
Throws
When the value does not match the schema (the promise rejects; its cause holds the details).
Inherited from
Call Signature
staticvalidateAsync<T>(data,schema):Promise<T>
Validate a value against a schema (the class schema when none is given), asynchronously: the external rules of the schema (.external()) run, which the synchronous validation cannot run.
Type Parameters
T
T = any
Parameters
data
T
The value to check.
schema
The schema to check against, instead of the class schema.
Returns
Promise<T>
A promise of the validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).
Throws
When the value does not match the schema (the promise rejects; its cause holds the details).
Inherited from
Call Signature
staticvalidateAsync<T>(data,schema,options):Promise<T>
Validate a value against a schema (the class schema when none is given), asynchronously: the external rules of the schema (.external()) run, which the synchronous validation cannot run.
Type Parameters
T
T = any
Parameters
data
T
The value to check.
schema
The schema to check against, instead of the class schema.
options
The validation options, merged with the defaults (unknown keys removed, the first error only).
Returns
Promise<T>
A promise of the validated value: the defaults applied, the unknown keys removed (a plain object, not a DTO instance).
Throws
When the value does not match the schema (the promise rejects; its cause holds the details).