Configuration

Running your own PostgreSQL server? Using S3 for file storage? It sounds like you need to configure Overview.

The only way to configure Overview is environment variables.

In overview-local, you set environment variables by editing the file config/overview.env. (Use config/overview.defaults.env as a guide.)

If you aren't using overview-local, we assume you know how to set environment variables.

So, what are you waiting for? Get configuring!

Environment variables

Defaults are for overview-local configuration.

Variable	Default	Meaning
OV_APPLICATION_SECRET	(a long string)	Set this to a 100-char random string, or a hacker could fake cookies and log in
OV_MULTI_USER	false	If false, there is only one user, [email protected], who is always logged in
OV_WELCOME_BANNER	(empty)	Message to display on welcome screen (if multi-user). Show a logo if not set.
OV_BRAND_FAVICON_ICO_URL	(internal)	URL for a <link rel="shortcut icon" href="..." />
OV_BRAND_LOGO_H40PX_URL	(internal)	URL for the logo displayed in the navbar. The logo height must be 40px, and it should include the brand name.
OV_BRAND_LOGO_H40PX_2X_URL	(internal)	URL for a "2x" (Retina) logo displayed in the navbar.
OV_BRAND_LOGO_H40PX_WIDTH_PX	(internal)	Width of OV_BRAND_LOGO_H40PX_URL. If you set OV_BRAND_LOGO_H40PX_URL and do not set OV_BRAND_LOGO_H40PX_WIDTH_PX, your logo will appear distorted.
OV_BRAND_CONTACT_URL	default	"Contact" link displayed in the navbar and in emailed notifications.
OV_URL	(unset)	If set, redirect users to this URL if they reached Overview via another URL
OV_DOMAIN_NAME	(unset)	See overview-local docs. We encourage you to set OV_URL and OV_MULTI_USER if you set this, so errors in your configuration won't make all your documents public.
OV_ALLOW_REGISTRATION	true	Allow anyone to register a new account
OV_ADMIN_ONLY_EXPORT	false	Allow only admin users to export and share document sets
OV_N_DOCUMENT_IDENTIFIERS	4	Maximum number of content-type detections to perform at once. These are usually cheap, but sometimes they involve networking. (worker only)
OV_MAX_DOCUMENTS	2000000	Maximum number of documents per document set
OV_MAX_CHARS_PER_DOCUMENT	655360	Maximum number of characters to ingest in a document. Subsequent characters will be ignored. To estimate RAM cost, multiply this number by 1,000.
OV_CLUSTERING_MEMORY	2500m	Maximum amount of memory to use when building a Tree
OV_MAX_MB_PER_SORT	200	Maximum amount of memory to use when the user sorts a document set by a metadata field (in MB). Overview will use temporary files when you surpass this; they're a bit slower.
OV_N_CONCURRENT_SORTS	2	Maximum number of document sets to sort simultaneously (for multi-user installations). (Maximum system-wide sort memory will be this times OV_MAX_MB_PER_SORT.)
SMTP_HOST, SMTP_PORT, SMTP_SSL, SMTP_TLS, SMTP_USERNAME, SMTP_PASSWORD, MAIL_FROM	(unset)	SMTP server settings. If unset, emails will be printed to standard output. Overview uses SMTP for user registration and password reset.
OV_SEARCH_DIRECTORY	./search	Where to store search-index data
DATABASE_SERVER_NAME	localhost	PostgreSQL hostname
DATABASE_PORT	5432	PostgreSQL port
DATABASE_NAME	overview	PostgreSQL database name
DATABASE_USERNAME	overview	PostgreSQL username, owner of the database
DATABASE_PASSWORD	overview	PostgreSQL password; set anything if auth method is trust
DATABASE_SSL		If true, use SSL
DATABASE_SSL_FACTORY		If org.postgresql.ssl.NonValidatingFactory, don't validate server certificate even if DATABASE_SSL is true
BLOB_STORAGE_FILE_BASE_DIRECTORY	./blob-storage	Where to store files (uploaded files will be written in this folder after they're processed)
BLOB_STORAGE_PAGE_DATA_LOCATION	file:page-data	Where to store page images. Use s3:my-overview-page-data-bucket for S3
BLOB_STORAGE_FILE_CONTENTS_LOCATION	file:file-contents	Where to store original uploaded files after they're processed
BLOB_STORAGE_FILE_VIEW_LOCATION	file:file-view	Where to store searchable-PDF representations of uploaded files
MESSAGE_BROKER_HOSTNAME	localhost	Address of worker, accessible to frontend
MESSAGE_BROKER_PORT	9030	Port of worker, accessible to frontend
MESSAGE_BROKER_CLIENT_HOSTNAME	localhost	Address of frontend, accessible to worker
MESSAGE_BROKER_CLIENT_PORT	9031	Port of frontend, accessible to worker
REDIS_HOST	localhost	Address of Redis server
REDIS_PORT	9020	Port of Redis server
DOCUMENTCLOUD_URL	https://www.documentcloud.org	If you're running against a custom DocumentCloud server, set this
GOOGLE_ANALYTICS_ID	(unset)	If set, use Google Analytics
INTERCOM_APP_ID, INTERCOM_SECRET_KEY	(unset)	If set, replace "Contact us" link with a "Talk to us" link that uses Intercom

Notes

• Our sbt test and development environments ignore some of these environment variables. If you're having trouble setting them, fiddle with project/Build.scala. (Are you sure you know what you're doing? You shouldn't need to change these variables. Tread carefully.)
• To understand where these variables are read, look at common/src/main/resources/reference.conf (shared settings), worker/src/main/conf/application.conf (worker settings) and conf/application.conf (server settings).