.env.example

# Hymical Forms configuration.
#
# Copy this file to `.env`, or set the same variables in your process environment.
# FORMS_DATABASE_URL is required. Everything below it is optional and shown with
# its built-in default; uncomment the lines you want to change.
#
# Management API keys are not configured here and there is no variable for one.
# They live in the database so that creating and revoking a key needs no restart.
# Create the first one with:
#
#     python -m hymical_forms.cli create-key --name local-admin

# SQLAlchemy database URL. PostgreSQL is the intended production database.
# Alembic reads this too, so `alembic upgrade head` needs nothing else set.
FORMS_DATABASE_URL=postgresql+psycopg://forms:forms@localhost:5432/forms

# SQLite is supported for local experimentation and backs the test suite. It is
# not a supported production target.
# FORMS_DATABASE_URL=sqlite:///./forms.db

# Largest request body accepted, in bytes. File uploads are not supported, so
# this only needs to accommodate text form fields.
# FORMS_MAX_BODY_BYTES=262144

# Largest number of name/value pairs accepted in one submission. A repeated
# field name (a checkbox group) counts once per submitted value.
# FORMS_MAX_FIELDS=100

# Largest field name accepted, in characters.
# FORMS_MAX_FIELD_NAME_LENGTH=128

# Largest field value accepted, in characters.
# FORMS_MAX_FIELD_VALUE_LENGTH=16384

# How long to wait for a webhook destination to accept a connection, in seconds.
# FORMS_WEBHOOK_CONNECT_TIMEOUT_SECONDS=5

# How long to wait for a webhook destination to respond, in seconds.
# FORMS_WEBHOOK_READ_TIMEOUT_SECONDS=10

# How many delivery attempts a submission gets before it is given up on.
# FORMS_WEBHOOK_MAX_ATTEMPTS=5

# Wait before the second attempt, in seconds. Each later wait doubles it.
# FORMS_WEBHOOK_RETRY_INITIAL_SECONDS=10

# Cap on the wait between attempts, however far the backoff has doubled.
# FORMS_WEBHOOK_RETRY_MAX_SECONDS=3600

# How long the worker waits before looking for due deliveries again, in seconds.
# FORMS_WORKER_POLL_SECONDS=1

# How many deliveries a worker claims at once.
# FORMS_WORKER_BATCH_SIZE=10

# How long a worker's claim on a delivery holds, in seconds. After this the
# delivery becomes claimable again, which is how work is recovered from a worker
# that died holding it.
# FORMS_WORKER_LEASE_SECONDS=60

# Permit webhook destinations on loopback and private addresses, so a webhook can
# point at a server on your own machine. Development only: enabling this in
# production lets anyone who can create an endpoint reach your internal network.
# FORMS_ALLOW_PRIVATE_WEBHOOK_TARGETS=false

# --- submission retrieval and retention ---------------------------------------

# How many days a stored submission is kept before an operator's cleanup command
# may delete it. 0, the default, keeps submissions indefinitely.
#
# Nothing is ever deleted automatically. Setting this only makes older
# submissions eligible; the sweep is a command you run:
#
#     python -m hymical_forms.cli cleanup-submissions --dry-run
#     python -m hymical_forms.cli cleanup-submissions
#
# A submission whose webhook delivery is still pending, processing, or failed and
# therefore replayable is never deleted, however old it is, because the payload
# is built from the submission at the moment it is sent.
# FORMS_SUBMISSION_RETENTION_DAYS=0

# Largest number of submissions one export may return. A filter matching more
# than this is refused rather than silently truncated, so an export is either
# complete or an error. Narrow the range and export it in parts.
# FORMS_EXPORT_MAX_SUBMISSIONS=10000

# --- public ingestion rate limiting -------------------------------------------
#
# These apply only to POST /f/{endpoint_id}. Management routes and /health are
# not affected. Counters live in PostgreSQL, so every API process enforces the
# same limit rather than one each.

# Enforce the public ingestion rate limits. On by default, because a public route
# with no limit is the exposure this exists to close. Turn it off only for local
# development or a test that is about something else.
# FORMS_RATE_LIMIT_ENABLED=true

# Submission attempts one source address may make per window, and how long that
# window lasts in seconds.
# FORMS_RATE_LIMIT_IP_REQUESTS=60
# FORMS_RATE_LIMIT_IP_WINDOW_SECONDS=60

# Submission attempts one endpoint may receive per window, from every source
# together, and how long that window lasts in seconds. This is the limit that
# answers an attack spread across many addresses.
# FORMS_RATE_LIMIT_ENDPOINT_REQUESTS=600
# FORMS_RATE_LIMIT_ENDPOINT_WINDOW_SECONDS=60

# Secret keying the digest that client addresses are counted under. Optional.
# Without it the digest is unkeyed, which keeps addresses out of the table but is
# not privacy against anyone who can read it, because the address space is small
# enough to enumerate. Every API process must be given the same value, or they
# will count the same client under different subjects.
# FORMS_RATE_LIMIT_IP_SECRET=

# How many reverse proxies of your own stand in front of this process. 0, the
# default, means the client address is the socket peer and X-Forwarded-For is
# ignored entirely. Set it to the real number of hops, never higher: a value
# larger than your actual chain lets clients choose their own rate limit bucket.
# FORMS_TRUSTED_PROXY_HOPS=0