diff --git a/.env.sample b/.env.sample index dc8f8011..1b41ae5f 100644 --- a/.env.sample +++ b/.env.sample @@ -1,31 +1,40 @@ -# Copy this file to .env, remove this comment and change the keys. For development -# with docker this should mostly work out of the box other than setting the Slack -# keys (for auth) and the SECRET_KEY. -# -# Please use `openssl rand -hex 32` to create SECRET_KEY +# 👋 Welcome, we're glad you're setting up an installation of Outline. Copy this +# file to .env or set the variables in your local environment manually. For +# development with docker this should mostly work out of the box other than +# setting the Slack keys and the SECRET_KEY. + + + + +# –––––––––––––––– REQUIRED –––––––––––––––– + +# Generate a unique random key, you can use `openssl rand -hex 32` in terminal +# DO NOT LEAVE UNSET SECRET_KEY=generate_a_new_key + +# Generate a unique random key, you can use `openssl rand -hex 32` in terminal +# DO NOT LEAVE UNSET UTILS_SECRET=generate_a_new_key +# For production point these at your databases, in development the default +# should work out of the box. DATABASE_URL=postgres://user:pass@localhost:5532/outline DATABASE_URL_TEST=postgres://user:pass@localhost:5532/outline-test REDIS_URL=redis://localhost:6479 -# Must point to the publicly accessible URL for the installation +# URL should point to the fully qualified, publicly accessible URL. If using a +# proxy the port in URL and PORT may be different. URL=http://localhost:3000 PORT=3000 -# Optional. If using a Cloudfront distribution or similar the origin server -# should be set to the same as URL. -CDN_URL= +# Third party signin credentials, at least one of EITHER Google OR Slack is +# required for a working installation or you'll have no sign-in options. -# enforce (auto redirect to) https in production, (optional) default is true. -# set to false if your SSL is terminated at a loadbalancer, for example -FORCE_HTTPS=true - -ENABLE_UPDATES=true -DEBUG=cache,presenters,events,emails,mailer,utils,multiplayer,server,services - -# Third party signin credentials (at least one is required) +# To configure Slack auth, you'll need to create an Application at +# => https://api.slack.com/apps +# +# When configuring the Client ID, add a redirect URL under "OAuth & Permissions": +# https:///auth/slack.callback SLACK_KEY=get_a_key_from_slack SLACK_SECRET=get_the_secret_of_above_key @@ -33,22 +42,59 @@ SLACK_SECRET=get_the_secret_of_above_key # => https://console.cloud.google.com/apis/credentials # # When configuring the Client ID, add an Authorized redirect URI: -# https:///auth/google.callback +# https:///auth/google.callback GOOGLE_CLIENT_ID= GOOGLE_CLIENT_SECRET= -# Comma separated list of domains to be allowed (optional) -# If not set, all Google apps domains are allowed by default + + + +# –––––––––––––––– OPTIONAL –––––––––––––––– + +# If using a Cloudfront/Cloudflare distribution or similar it can be set below. +# This will cause paths to javascript, stylesheets, and images to be updated to +# the hostname defined in CDN_URL. In your CDN configuration the origin server +# should be set to the same as URL. +CDN_URL= + +# Auto-redirect to https in production. The default is true but you may set to +# false if you can be sure that SSL is terminated at an external loadbalancer. +FORCE_HTTPS=true + +# Have the installation check for updates by sending anonymized statistics to +# the maintainers +ENABLE_UPDATES=true + +# You may enable or disable debugging categories to increase the noisiness of +# logs. The default is a good balance +DEBUG=cache,presenters,events,emails,mailer,utils,multiplayer,server,services + +# Comma separated list of domains to be allowed to signin to the wiki. If not +# set, all domains are allowed by default when using Google OAuth to signin GOOGLE_ALLOWED_DOMAINS= -# Third party credentials (optional) -SLACK_VERIFICATION_TOKEN=PLxk6OlXXXXXVj3YYYY +# For a complete Slack integration with search and posting to channels the +# following configs are also needed, some more details +# => https://wiki.generaloutline.com/share/be25efd1-b3ef-4450-b8e5-c4a4fc11e02a +# +SLACK_VERIFICATION_TOKEN=your_token SLACK_APP_ID=A0XXXXXXX SLACK_MESSAGE_ACTIONS=true + +# Optionally enable google analytics to track pageviews in the knowledge base GOOGLE_ANALYTICS_ID= + +# Optionally enable Sentry (sentry.io) to track errors and performance SENTRY_DSN= -# AWS credentials (optional in development) +# To support uploading of images for avatars and document attachments an +# s3-compatible storage must be provided. AWS S3 is recommended for redundency +# however if you want to keep all file storage local an alternative such as +# minio (https://github.com/minio/minio) can be used. + +# A more detailed guide on setting up S3 is available here: +# => https://wiki.generaloutline.com/share/125de1cc-9ff6-424b-8415-0d58c809a40f +# AWS_ACCESS_KEY_ID=get_a_key_from_aws AWS_SECRET_ACCESS_KEY=get_the_secret_of_above_key AWS_REGION=xx-xxxx-x @@ -56,11 +102,10 @@ AWS_S3_UPLOAD_BUCKET_URL=http://s3:4569 AWS_S3_UPLOAD_BUCKET_NAME=bucket_name_here AWS_S3_UPLOAD_MAX_SIZE=26214400 AWS_S3_FORCE_PATH_STYLE=true -# uploaded s3 objects permission level, default is private -# set to "public-read" to allow public access AWS_S3_ACL=private -# Emails configuration (optional) +# To support sending outgoing transactional emails such as "document updated" or +# "you've been invited" you'll need to provide authentication for an SMTP server SMTP_HOST= SMTP_PORT= SMTP_USERNAME= @@ -71,6 +116,6 @@ SMTP_REPLY_EMAIL= # Custom logo that displays on the authentication screen, scaled to height: 60px # TEAM_LOGO=https://example.com/images/logo.png -# See translate.getoutline.com for a list of available language codes and their -# percentage translated. +# The default interface language. See translate.getoutline.com for a list of +# available language codes and their rough percentage translated. DEFAULT_LANGUAGE=en_US \ No newline at end of file diff --git a/README.md b/README.md index 7ca717d2..ef7f63f1 100644 --- a/README.md +++ b/README.md @@ -33,26 +33,27 @@ Outline requires the following dependencies: ### Production -For a manual self-hosted production installation these are the suggested steps: +For a manual self-hosted production installation these are the recommended steps: -1. Clone this repo and install dependencies with `yarn install` -1. Build the source code with `yarn build` -1. Using the `.env.sample` as a reference, set the required variables in your production environment. The following are required as a minimum: - 1. `SECRET_KEY` (follow instructions in the comments at the top of `.env`) - 1. `SLACK_KEY` (this is called "Client ID" in Slack admin) - 1. `SLACK_SECRET` (this is called "Client Secret" in Slack admin) - 1. `DATABASE_URL` (run your own local copy of Postgres, or use a cloud service) - 1. `REDIS_URL` (run your own local copy of Redis, or use a cloud service) - 1. `URL` (the public facing URL of your installation) - 1. `AWS_` (all of the keys beginning with AWS) -1. Migrate database schema with `yarn sequelize:migrate`. Production assumes an SSL connection, if -Postgres is on the same machine and is not SSL you can migrate with `yarn sequelize:migrate --env=production-ssl-disabled`. -1. Start the service with any daemon tools you prefer. Take PM2 for example, `NODE_ENV=production pm2 start ./build/server/index.js --name outline ` +1. First setup Redis and Postgres servers, this is outside the scope of the guide. +1. Download the latest official Docker image, new releases are available around the middle of every month: + + `docker pull outlinewiki/outline` +1. Using the [.env.sample](.env.sample) as a reference, set the required variables in your production environment. You can export the environment variables directly, or create a `.env` file and pass it to the docker image like so: + + `docker run --env-file=.env outlinewiki/outline` +1. Setup the database with `yarn sequelize:migrate`. Production assumes an SSL connection to the database by default, if +Postgres is on the same machine and is not SSL you can migrate with `yarn sequelize:migrate --env=production-ssl-disabled`, for example: + + `docker run --rm outlinewiki/outline yarn sequelize:migrate` +1. Start the container: + + `docker run outlinewiki/outline` 1. Visit http://you_server_ip:3000 and you should be able to see Outline page > Port number can be changed using the `PORT` environment variable -1. (Optional) You can add an `nginx` reverse proxy to serve your instance of Outline for a clean URL without the port number, support SSL, etc. +1. (Optional) You can add an `nginx` or other reverse proxy to serve your instance of Outline for a clean URL without the port number, support SSL, etc. ### Development