Configuration

The Citeck Launcher server mode configuration is stored in two YAML files in the /opt/citeck/conf/ directory.

namespace.yml

The main platform configuration file. Defines which components to start and how to configure them.

Location: /opt/citeck/conf/namespace.yml

Structure

apiVersion: v1

# Идентификатор namespace (генерируется автоматически)
id: citeck-abc123

# Отображаемое имя
name: Citeck

# Ссылка на бандл (набор Docker-образов определённой версии)
bundleRef: "community:2024.11"

# Снапшот для инициализации (демо-данные)
snapshot: with-demo-data

# Настройки прокси
proxy:
  host: 203.0.113.45
  port: 443
  tls:
    enabled: true
    letsEncrypt: true
    certFile: ""
    keyFile: ""

# Аутентификация
authentication:
  type: keycloak
  users:
    - admin

# PgAdmin (веб-интерфейс PostgreSQL)
pgAdmin:
  enabled: false

# Настройки веб-приложений (переопределение параметров из бандла)
webapps:
  eapps:
    heapSize: 1024m
  emodel:
    heapSize: 768m
    env:
      CUSTOM_PROPERTY: value

# Настройки Email (SMTP)
email:
  host: smtp.example.com
  port: 587
  tls: true
  from: noreply@example.com
  username: mailuser

# Настройки S3-совместимого хранилища
s3:
  endpoint: https://s3.example.com
  bucket: citeck-data
  accessKey: AKIAIOSFODNN
  region: us-east-1

Secret fields (reference format)

Fields containing sensitive data (s3.secretKey, email.password, etc.) are stored in namespace.yml not as plain values but as references in the format secret:<key_name>:

s3:
  endpoint: https://s3.example.com
  bucket: ecos-content
  accessKey: minio-user
  secretKey: secret:s3.secretKey     # ссылка, не plain-значение
email:
  host: smtp.example.com
  port: 587
  from: noreply@example.com
  password: secret:email.password    # ссылка

The actual values are encrypted and stored in /opt/citeck/conf/secrets/*.json. The launcher automatically resolves references when generating container environment variables.

When using citeck setup commands (e.g. setup s3), references are created/updated automatically — direct editing of namespace.yml is normally not required.

Main sections

bundleRef

Defines the platform version. Format: repo:key, e.g. community:2024.11.

• repo — bundle repository identifier (community or enterprise)

• key — bundle version

To change the version, use citeck upgrade.

template

Reference to the namespace template from the workspace configuration (workspace-v1.yml). Set automatically during citeck install. Templates may define applications that are disabled by default:

# В workspace-v1.yml
namespaceTemplates:
  - id: default
    name: Default
    config:
      bundleRef: 'community:LATEST'
    detachedApps:
      - onlyoffice

Applications listed in detachedApps are not started on first launch. To enable them: citeck start <app>.

proxy

Proxy server settings (entry point for all HTTP requests):

Parameter	Type	Description
host	string	Server IP address or domain name
port	int	Port (443 for HTTPS, 80 for HTTP)
tls.enabled	bool	Enable HTTPS
tls.letsEncrypt	bool	Use Let’s Encrypt to obtain a certificate
tls.certFile	string	Path to the custom certificate file
tls.keyFile	string	Path to the custom key file

authentication

Platform authentication type:

• keycloak — authentication via Keycloak (recommended for production)

• basic — basic HTTP authentication (for development)

webapps

Override settings for individual applications. Each application may have:

Parameter	Type	Description
heapSize	string	Java heap size (e.g. 1024m, 2g)
memoryLimit	string	Docker container memory limit
env	map	Additional environment variables
image	string	Override the Docker image

email (optional)

SMTP settings for sending notifications:

email:
  host: smtp.example.com
  port: 587
  tls: true
  from: noreply@example.com
  username: mailuser
  # Пароль хранится в зашифрованном хранилище секретов

Note

The SMTP password is set via citeck setup email and stored in encrypted form, not in the configuration file.

The tls field and port mapping:

SMTP transport is controlled by the boolean tls field. The generator translates it into the Spring Mail protocol (smtp or smtps) used by web applications.

Value	Typical port	Description
true	587	SMTP with STARTTLS (Spring Mail protocol smtp + starttls.enable=true). The recommended mode for most external SMTP servers.
false	25	Unencrypted SMTP (Spring Mail protocol smtp). Used primarily for internal relays.

If the username (username) is left empty, SMTP authentication is disabled — this is acceptable for relays that accept unauthenticated submissions.

s3 (optional, Enterprise only)

S3-compatible object storage settings. Available only in Enterprise bundles that include the ecos-content application.

s3:
  endpoint: https://s3.example.com
  bucket: citeck-data
  accessKey: AKIAIOSFODNN
  region: us-east-1
  # Secret key хранится в зашифрованном хранилище секретов

Compatible with Amazon S3, MinIO, and other S3-compatible storage systems.

Note

In the citeck setup menu, the S3 item is shown only when the ecos-content application is present in the bundle. On Community bundles it is hidden.

daemon.yml

Configuration of the daemon itself (the Citeck Launcher process).

Location: /opt/citeck/conf/daemon.yml

Structure

# Язык интерфейса CLI (en, ru, zh, es, de, fr, pt, ja)
locale: ru

# Настройки встроенного сервера (внутреннее; не изменяйте -- формат может меняться)
server:
  webui:
    enabled: true
    listen: "127.0.0.1:7088"

# Настройки реконсилера (мониторинг и автовосстановление)
reconciler:
  interval: 60              # интервал проверки в секундах
  livenessPeriod: 30000     # период liveness-проверок в мс
  livenessEnabled: true     # включить liveness-проверки

# Настройки Docker
docker:
  pullConcurrency: 4        # параллельных загрузок образов
  stopTimeout: 10           # таймаут остановки контейнера в секундах

Parameters

locale

Language for CLI messages. Supported values: en, ru, zh, es, de, fr, pt, ja.

To change: citeck setup language

reconciler

The reconciler automatically monitors application state and restarts failed ones:

• interval — how often to check state (default: 60 seconds)

• livenessPeriod — liveness check period (default: 30 seconds)

• livenessEnabled — enable/disable liveness checks (default: true)

When an application fails, the reconciler uses exponential backoff for restart retries (from 1 minute up to a maximum of 30 minutes).

docker

• pullConcurrency — number of parallel Docker image downloads (default: 4)

• stopTimeout — time to wait for graceful container shutdown before SIGKILL (default: 10 seconds)

Configuration via citeck setup

The citeck setup command provides a convenient interactive interface for changing configuration without manually editing YAML files.

Note

Interactive CLI access to these settings and a detailed description of the flags for individual subcommands (setup hostname, setup email, setup s3, setup admin-password, etc.) are described in Command Reference, section “setup”.

Hostname (citeck setup hostname)

Change the IP address or domain name. Affects:

• Platform URL

• TLS certificates

• Keycloak configuration

TLS (citeck setup tls)

Switch the TLS mode. Affects certificates and ports.

Auth (citeck setup auth)

Switch the authentication type between Keycloak and Basic.

Warning

Switching from Basic to Keycloak requires a restart of all components. Switching from Keycloak to Basic deletes all Keycloak user accounts.

Resources (citeck setup resources)

Configure application resources (heap size, memory limit). Useful for optimizing memory consumption on resource-constrained servers.

Admin password (citeck setup admin-password)

Change the administrator password. Applied to the components:

• Keycloak (realm ecos-app — user login)

• RabbitMQ

• PgAdmin

The change is applied via the services’ APIs at runtime, without restarting containers.

Note

Internal platform operations (Keycloak configuration, OIDC client updates, password changes) are performed under the stable citeck service account (in the Keycloak master realm and in RabbitMQ). This allows citeck setup admin-password to change the human administrator passwords in the Keycloak / RabbitMQ / PgAdmin admin UIs without affecting platform operation — the launcher continues to use the citeck SA for its internal operations.

TLS modes

Mode	Description
Auto HTTPS	Automatic selection: tries Let’s Encrypt and falls back to a self-signed certificate on failure. The recommended mode.
Let’s Encrypt	Obtain a trusted certificate from Let’s Encrypt. Supports both domain names and IP addresses (via the shortlived profile; certificates are renewed every ~6 days).
Self-signed	Automatically generate a self-signed certificate. Browsers will show a security warning.
Custom	Use your own certificate and key files. Specify paths to cert.pem and key.pem.
HTTP only	No encryption. For test environments only.

Administrator password

Generation at installation

On the first launch in server mode, a random administrator password is automatically generated. It is applied to:

• Keycloak (user admin in realm ecos-app; the master realm is managed separately by the citeck service account)

• RabbitMQ (user admin)

• PgAdmin (admin@admin.com)

The password is displayed once in the installation wizard output.

Note

Unlike desktop mode, which uses the standard admin password, server mode generates a unique password for each installation.

Changing the password

citeck setup admin-password

The command:

1. Prompts for the new password (with confirmation)

2. Applies it to Keycloak via kcadm.sh

3. Applies it to RabbitMQ via rabbitmqctl

4. Applies it to PgAdmin via setup.py

5. Reloads web applications to apply the updated RabbitMQ password

The password persists across restarts and updates.

Directory structure

/opt/citeck/                 # Корневая директория (CITECK_HOME)
+-- conf/                    # Конфигурация
|   +-- namespace.yml        # Конфигурация платформы
|   +-- daemon.yml           # Конфигурация демона
|   \-- secrets/             # Зашифрованные секреты (AES-256-GCM)
+-- data/                    # Данные
|   +-- repo/                # Git-клоны workspace и бандлов
|   \-- runtime/             # Данные контейнеров (volumes)
\-- log/                     # Логи
    \-- daemon.log           # Лог демона (ротация)

/run/citeck/
\-- daemon.sock              # Unix-сокет для CLI-демон коммуникации

/usr/local/bin/
+-- citeck                   # Основной бинарный файл
\-- citeck.bak               # Резервная копия (для rollback)

/etc/systemd/system/
\-- citeck.service           # Systemd unit-файл

Environment variables

Variable	Description
CITECK_HOME	Root directory (default: /opt/citeck)
CITECK_RUN	Directory for sockets (default: /run/citeck)