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	(unset)	Message to display on welcome screen (if multi-user). Show a logo if not set.
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_CONVERTERS	1	Maximum total number of PDF/LibreOffice/Tesseract processes to run simultaneously (each takes 100% CPU, so don't set this higher than the number of processors) (worker only)
OV_MAX_DOCUMENTS	2000000	Maximum number of documents per document set
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.)
OV_PDF_MEMORY	1400m	Maximum amount of memory to use when processing an uploaded PDF
OV_TESSERACT_PATH	tesseract	Location of tesseract executable (worker only)
OV_LIBRE_OFFICE_PATH	soffice (you should change this)	Location of soffice executable. Do set this to the absolute path to soffice.bin, or Overview won't be able to stop LibreOffice when it hits an infinite loop from an invalid input file (worker only)
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).