Documentation / Getting started

Settings

Every setting in the .env file, what it does and which ones you must never change.

All settings live in /opt/closeyourit/.env. After a change, run:

closeyourit restart

The AI service is not set here: it has its own page in the administration area. See AI.

Address

Variable	Use
`DOMAIN`	the address Caddy serves and asks the HTTPS certificate for
`ACME_EMAIL`	email for the HTTPS certificate
`APP_HOSTS`	every address the app answers on, comma separated; the first is the main one
`MAIL_HOST`	the address used in links inside emails; defaults to the first of `APP_HOSTS`
`APP_BASE_URL`	the full public address, if it is not `https://` plus the main host

To change domain, change DOMAIN, APP_HOSTS and MAIL_HOST together, point the new domain to the server, then restart.

Email

Variable	Default	Use
`SMTP_ADDRESS`	empty	the SMTP server; empty means no email is sent
`SMTP_PORT`	`587`	the port
`SMTP_USERNAME`, `SMTP_PASSWORD`	empty	credentials; leave both empty for a server without login
`SMTP_AUTHENTICATION`	`plain`	the login method, used only with a username
`SMTP_STARTTLS`	`true`	set to `false` for a server that does not offer STARTTLS
`MAIL_FROM`	`CloseYourIt <noreply@your-domain>`	the sender

Uploaded files

Uploads stay on the server disk, in the Docker volume closeyourit_storage. To keep them on Amazon S3 instead:

Variable	Use
`AWS_S3_BUCKET`	the bucket; setting it switches uploads to S3
`AWS_REGION`	the region; defaults to `eu-central-1`
`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`	the credentials

Only Amazon S3 is supported: there is no setting for the address of another S3-compatible service.

Files uploaded before the switch stay on the disk and are not moved.

Variable	Use
`BACKUP_S3_BUCKET`	also send each database backup to this bucket, with the `AWS_*` credentials above

Capacity

Leave these alone until the server is clearly too busy.

Variable	Default	Use
`WEB_CONCURRENCY`	1	processes that answer web requests
`JOB_CONCURRENCY`	1	processes for general background work
`INGEST_JOB_CONCURRENCY`	1	processes that save incoming errors, logs and metrics
`EMBEDDINGS_JOB_CONCURRENCY`	1	processes that prepare text for AI search
`RAILS_LOG_LEVEL`	`info`	how much the app writes in its log (`debug`, `info`, `warn`, `error`)

Each extra process uses more memory. On a 4 GB server raise one value at a time.

Integrations

Variable	Use
`GH_APP_ID`, `GH_APP_SLUG`, `GH_APP_PRIVATE_KEY`, `GH_APP_CLIENT_ID`, `GH_APP_CLIENT_SECRET`, `GH_WEBHOOK_SECRET`	the GitHub App
`TELEGRAM_BOT_TOKEN`, `TELEGRAM_BOT_USERNAME`, `TELEGRAM_WEBHOOK_SECRET`	a Telegram bot for notifications
`MAXMIND_LICENSE_KEY`	a free MaxMind license key: the country database for web analytics is then downloaded and kept fresh by itself; see below
`GEOIP_DB_PATH`	where the country database for web analytics is; see below

Create a bot with BotFather, set the three variables, restart, then register the bot once:

cd /opt/closeyourit
docker compose exec app bin/rails telegram:set_webhook
docker compose exec app bin/rails telegram:set_commands

Countries in web analytics

The country of a visit comes from a MaxMind GeoLite2 Country file, which CloseYourIt does not ship. Without it everything else works and the country stays empty.

Create a free MaxMind account, generate a license key, set it as MAXMIND_LICENSE_KEY and restart. Every night CloseYourIt downloads the file when it is missing or a week old, and starts using it without a restart. Administration → System health says whether the file is there and up to date.

Without a key you can copy the file by hand; it is not updated then:

cd /opt/closeyourit
docker compose cp GeoLite2-Country.mmdb app:/rails/storage/GeoLite2-Country.mmdb

Written by the installer

The closeyourit command manages these. Do not edit them by hand.

Variable	Managed by
`CLOSEYOURIT_VERSION`	`closeyourit update`
`INGEST_ENABLED`, `INGEST_UPSTREAM`	`closeyourit enable ingest` and `disable ingest`

Never change these

They are generated at install time. Changing or losing one makes existing data unreadable or locks the app out of its database.

Variable	Protects
`POSTGRES_PASSWORD`	the database
`SECRET_KEY_BASE`	sessions and signed links
`AR_ENCRYPTION_PRIMARY_KEY`, `AR_ENCRYPTION_DETERMINISTIC_KEY`, `AR_ENCRYPTION_KEY_DERIVATION_SALT`	encrypted columns in the database
`SECRET_ASSETS_MASTER_KEY`	the secrets vault

Keep a copy of .env outside the server: the database backups do not contain these keys.