teyfix/clickhouse repository overview

⁠teyfix/clickhouse

ClickHouse LTS with YAML provisioning, optional native Prometheus metrics, JSON log files, and a bounded migration command under Process Compose. Versions are centralized in docker-bake.hcl; native migrate is included for consumers that use golang-migrate, matching the Animalux precedent.

Mount /config/clickhouse.yaml:

databases: [app]
users:
  - name: writer
    password: { from_env: APP_PASSWORD }
    grants:
      - database: app
        privileges: [SELECT, INSERT, CREATE TABLE, ALTER]
  - name: reader
    password: { from_file: /run/secrets/reader_password }
    grants:
      - database: app
        privileges: [SELECT]
metrics: { enabled: true }
logging: { level: information }
memory_mb: 1024
migration:
  command: [/schema/migrate.sh]
  timeout_seconds: 120

The default migration is /bin/true. The consumer owns its schemas, tables, queries and migrations. A mounted script can invoke migrate or native clickhouse-client; the image imposes no application migration framework. Provisioning precedes migrations, and readiness requires both to finish. A nonzero exit or timeout fails startup visibly.

Database and user names use letters/digits/underscore, beginning with a letter or underscore. default and teyfix_bootstrap are reserved. Users require a password supplied from the environment or an absolute secret-file path. File passwords may end with a newline. Native SHA-256 password verifiers are sent to ClickHouse; plaintext passwords are never interpolated into SQL.

Each declared user's direct grants and role memberships are reconciled from the configuration on every startup. An empty or omitted grants list removes prior grants; role memberships are cleared. Do not share management of these named users with a separate provisioner. Absent users and databases are retained. Passwords rotate on the next startup. Supported privileges are ALL, SELECT, INSERT, ALTER, CREATE TABLE, CREATE VIEW, DROP TABLE, DROP VIEW, TRUNCATE, OPTIMIZE, and SHOW. Scope is a database's tables; explicitly using database: "*" grants across all databases. No grant option is assigned.

The published upstream engine/default server settings are retained, while the upstream application/user bootstrap is replaced with native repeatable SQL. There is no remotely usable anonymous/default user. An internal randomly credentialed account is restricted to loopback for initialization and health; its client config is private at /run/teyfix-clickhouse/client.xml. A trusted migration command may use that config for required DDL. All configuration and secret changes take effect after restarting the container.

HTTP is 8123, native TCP is 9000. metrics.enabled opts into ClickHouse's built-in Prometheus endpoint at :9363/metrics; a separate exporter would duplicate the native capability. Mount /var/log/clickhouse for native JSON server and error logs, rotated at 100 MB with three retained files and readable by external Vector. No collector runs in the image. Query logs remain native system tables; high-volume trace/metric system logs are disabled by default.

Mount /var/lib/clickhouse for data. Server memory defaults to 1024 MiB with bounded background thread pools; the Compose example⁠ uses 2 CPUs and 2 GiB. Create its secret file before starting. Bind paths use ${PWD} from the project root. docker compose down -v does not delete those bind mounts; explicitly remove only .state/clickhouse after stopping for a full local reset. Preserve reusable downloads under .cache/.

Build with docker buildx bake clickhouse --load; test with docker buildx bake clickhouse-smoke. CI repeats the native behavior tests on amd64 and arm64 before publication. Smoke coverage includes cold and retained startup, env/file credentials and rotation, grants and revocation, migrations, metrics toggling, JSON logs and shutdown.

The smoke fixture uses a 2 GiB server limit under BuildKit's QEMU emulator because its translated-code RSS exceeds the native fixture's 1 GiB limit. Native smoke checks and the image default retain 1 GiB.

Log directories can be overridden with paths.log in the service YAML. Native data directories remain unchanged.

Maintained from the source documentation⁠. See published tags⁠ and the service integration guide⁠.