chore: Improved deployment documentation (#1868)

.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://<URL>/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://<your Outline URL>/auth/google.callback
+# https://<URL>/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

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