Skip to content

docs: update config file reference - #363

Open
rbowen wants to merge 3 commits into
apache:mainfrom
rbowen:rbowen-configfile
Open

rbowen wants to merge 3 commits into
apache:mainfrom
rbowen:rbowen-configfile

Conversation

@rbowen

@rbowen rbowen commented Nov 11, 2026

Copy link
Copy Markdown

The config file page (docs/getting-started/configfile.md) had fallen out
of date with the configuration Answer actually uses. This PR rewrites it to
match the current code, and documents every setting the config file
supports.

What was wrong

  • The example showed MySQL as the default database. The default is now
    SQLite (sqlite3, at /data/sqlite3/answer.db).
  • The cache path was shown as /tmp/cache/cache.db. It is
    /data/cache/cache.db.
  • Several settings were missing entirely:
    • debug
    • data.database.max_open_conn, max_idle_conn, conn_max_life_time
    • service_config.clean_up_uploads,
      clean_orphan_uploads_period_hours, purge_deleted_files_period_days
    • ui.api_base_url
  • Most settings had no explanation beyond a short inline comment.
  • The environment variables that override the file at runtime
    (SITE_ADDR, SWAGGER_HOST, SWAGGER_ADDRESS_PORT) weren't mentioned.
  • The page only described Docker paths, with no mention of where the file
    lives for a binary install.

What this PR does

  • Replaces the example with the current default configs/config.yaml.
    Optional settings that are not set by default (debug and the three
    database connection pool settings) are included but commented out, so
    the example can be copied as-is.
  • Adds a section for each part of the file (server, data, i18n,
    swaggerui, service_config, ui), with a table giving each setting's
    default and what it does.
  • Adds a section on the environment variables that override settings at
    runtime, with an example.
  • Explains where the file is for Docker (/data/conf/config.yaml) and for
    the binary (the conf directory under the -C data directory), and
    that Answer must be restarted after changes.

Coverage and sources

The page covers every setting in the config structure Answer reads
(AllConfig in internal/base/conf/conf.go and the types it uses),
plus the ui keys read by the frontend build.

Each description is based on the code that uses the setting, not on its
name. A few behaviors worth reviewers' attention, all taken from the code:

  • max_open_conn is forced to 1 for SQLite (internal/base/data/data.go).
    The pool settings only take effect when greater than 0.
  • clean_up_uploads: false disables both cleanup jobs
    (internal/base/cron/cron.go).
  • Unused uploads aren't deleted immediately: every
    clean_orphan_uploads_period_hours they are moved to a deleted folder
    inside upload_path. Every purge_deleted_files_period_days, that whole
    folder is emptied (PurgeDeletedFiles in file_record_service.go). So
    purge_deleted_files_period_days is a schedule, not a retention period.
  • swaggerui.protocol, host, and address only affect links shown in
    the API documentation, not where Answer listens
    (internal/router/swagger_router.go).
  • ui.api_base_url adds a prefix to all API routes on the server
    (internal/base/server/http.go).
  • ui.public_url, api_url, and base_url are written into the frontend
    at build time (ui/scripts/env.js), so changing them requires a rebuild.
    api_url is used as the base URL for the frontend's API requests
    (ui/src/utils/request.ts).

Only docs/getting-started/configfile.md is changed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant