Project Configuration

Project Configuration

Part of FreeREG-Core-Records (shared with FreeCEN and FreeBMD).

Config: config/application.rb, config/environments/*.rb, config/initializers/*, and the YAML files in config/ (most git-ignored, created from the committed *.example.yml / *_example.yml)

Development-Setup explains how to get a working set of config files (bin/setup copies the examples). This page is the reference for what each file and key does and where the code reads it.

Which file does what

File (create from)	Loaded by	Purpose
freeukgen_application.yml (freeukgen_application_example.yml)	config_for(:freeukgen_application) in config/application.rb	Which site this process is, plus adverts and banners
mongo_config.yml (mongo_config.example.yml)	config.before_configuration → MyopicVicar::MongoConfig, then copied onto config.* in each config/environments/<env>.rb	Paths, feature flags, secrets, operational settings. Despite the name, it's mostly not MongoDB connection settings
mongoid.yml (mongoid_example.yml)	Mongoid	MongoDB connection: database name, hosts, client options
errbit.yml (errbit.example.yml)	config/initializers/errbit.rb	Error reporting (Error-Management)
application.yml (application.example.yml)	config.before_configuration → copied into ENV	Development mail: gmail_username, gmail_password, dev_mail_recipient
secrets.yml (secrets.example.yml)	config/initializers/secret_token.rb	Legacy secret_token. Cookie signing uses secret_key_base from mongo_config.yml
database.yml (database.example.yml)	Rails (ActiveRecord railtie)	Must exist for boot; not used (Architecture)
site_settings.yml	committed	asset_collection_name (legacy asset/transcription feature)
csv_layout.yml	committed	Name-role → entry-field mapping per record type (reference layout)
storage.yml, cable.yml	committed	Rails defaults; not used in practice

All per-environment YAML files are keyed by development / test / production.

freeukgen_application.yml

Key	Effect
template_set	freereg, freecen or freebmd. Read once at boot and drives the whole multi-skin system (Architecture): asset paths, _freereg/_freecen partial selection, config.freexxx_display_name, RecordType.all_types, the public_site_specific/<site> files copied into public/, and hundreds of inline branches. The example file defaults to freecen, so for FreeREG you must change it
advert_key (data_ad_client, data_ad_slot_*)	Google AdSense client and slot ids for the ad partials
gtm_key	Google Tag Manager id
cta_display_status	Whether the donate call-to-action is shown (Donate-Cta-Feedback)
server_upgrade	Upgrade mode: shows a notice in the nav and dashboard and makes session cookies expire after 3 seconds (config/initializers/session_store.rb), which logs everyone out
site_notice_banner_html	HTML for a site-wide notice banner

mongo_config.yml

Each key is copied onto Rails.application.config.<name> in config/environments/<env>.rb (some with unless … nil? guards). The code then reads Rails.application.config.<name>. A key missing from the YAML becomes nil, and features that depend on it fail at the point of use, not at boot.

Paths and files

Key	Used for
datafiles	Root of the per-user CSV folders: <datafiles>/<userid>/<file_name> and .attic/. The CSV processor, upload, download and replace all use it (Batch-Records-Freereg1CsvFile-and-Entry)
delete_list	Append-only list of removed batches, consumed by delete_file_no_sleep (FreeREG-Operations-and-Rake-Tasks)
register_embargo_list	Append-only list of registers whose embargo rules changed, consumed by foo:add_embargo_record. Not in mongo_config.example.yml, so add it by hand or embargo rule saves raise (Embargoes-and-Gaps)
files_for_processing, datafiles_delta, datafiles_changeset	Legacy FreeREG1 rsync/overnight-processing lists. Obsolete
backup_directory	Target folder for lib/tasks/backup.rake
mongodb_bin_location	Location of the MongoDB command-line tools (used by MasterPlaceName and legacy install docs)
vld_file_locations, fc_parms_upload_dir, fc1_coverage_stats, fc_update_processor_status_file	FreeCEN only

Feature flags and tuning

Key	Effect
member_open	false = maintenance mode: only system_administrator and technical can log in (Authentication-System)
ucf_support	Enables the UCF "possible matches" search (Search-Query-System)
witness_support	Shows witness fields in the UI (ApplicationHelper)
max_search_time	max_time_ms for search queries, in milliseconds
days_to_retain_search_queries	Age at which build:delete_search_queries deletes stored searches
days_to_retain_messages	Retention for messages, feedback and contacts (Message-System)
sleep	Seconds to sleep after each entry/search-record write in the CSV processor and deletion tasks. Throttles load on production MongoDB. Use 0 in development
emmendation_sleep	Sleep between records in emendation runs
freecen2_place_cache	FreeCEN: use Freecen2Place for the place picker. Leave unset/false for FreeREG: search code branches on it
donate_color	Colour of the fundraising/pledge call-to-action partials

External services and URLs

Key	Used for
website	This site's base URL (logs, emails)
image_server, image_server_access	Image server base URL and access setting (Image-Server-System)
github_issues_login, github_issues_password, github_issues_access_token, github_issues_repo	Turning contacts and feedback into GitHub issues (Contact-System, Feedback-System)
sendgrid_api_key	Read only by freereg:bounced_emails_set_invalid, which fetches SendGrid's bounce list. Mail itself is sent with sendmail (config/initializers/setup_mail.rb)

Secrets

Key	Used for
secret_key_base	Rails cookie and session signing (config.secret_key_base) and Devise's secret_key
our_secret_key	Secret key used by the password encryptor (Authentication-System). Must be identical on all servers sharing a database

Environments

config/environments/production.rb highlights: cache_classes/eager_load true, consider_all_requests_local = false, exceptions_app = routes (custom error pages, Error-Management), log_level :info, serve_static_files = false (the web server serves public/), dataset_date (a fixed display string), mongodb_collection_temp/mongodb_collection_location (temp and collection dump paths). Development and test read the same MongoConfig keys. test.rb reads a subset.

config/application.rb also defines MyopicVicar::Servers, the list of production host names. SoftwareVersion.extract_server(Socket.gethostname) uses these to stamp which server and code version processed a batch.

Adding a new setting

1. Add the key to config/mongo_config.example.yml under every environment, with a comment. Several current keys are missing from the example (register_embargo_list, days_to_retain_messages, sendgrid_api_key, citation, dragonfly_secret_code, freecen2_place_cache, donate_color, github_issues_access_token), and that's the most common cause of "works on the server, nil locally".
2. Copy it onto config.<name> in development.rb, production.rb and (if tests need it) test.rb.
3. Read it as Rails.application.config.<name>, and handle nil.
4. Tell the sysadmins, since the real mongo_config.yml on each server is edited by hand.

Keys copied in production.rb that no app code reads: wildcard_support, citation, dragonfly_secret_code. They're safe to leave blank.