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

Variable	Default	Meaning
APPLICATION_SECRET	(a long string)	Set this to a 100-char random string, or any hacker will be able to log in as any user
OVERVIEW_MULTI_USER	true	If false, there is only one user, [email protected], who is always logged in
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.
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
DOCUMENTCLOUD_URL	https://www.documentcloud.org	If you're running against a custom DocumentCloud server, set this
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
ES_HOSTS	127.0.0.1:9200	ElasticSearch HTTP servers, as comma-separated addr:port pairs. Choose the 9200-9299 range of ports, not the 9300-9399 range.
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
CLUSTERING_MEMORY	2500m	Maximum amount of memory to use when building a Tree
PDF_MEMORY	1400m	Maximum amount of memory to use when processing an uploaded PDF
MAX_DOCUMENTS	2000000	Maximum number of documents per document set
LIBRE_OFFICE_PATH	soffice (but you should change it)	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)
TESSERACT_PATH	tesseract	Location of tesseract executable (worker only)
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)
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

Notes

• overview-local overrides some of these defaults -- in particular, OVERVIEW_MULTI_USER=false by default.
• 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).