From 5f91e7dd9d846349a0b8be942a35c3ad26d809f8 Mon Sep 17 00:00:00 2001 From: Michael Grosser Date: Sun, 7 Oct 2018 17:33:53 -0700 Subject: [PATCH] stop duplicating settings in .env.example and docs/setup.md --- .env.example | 147 +++++++++++++++++++++++++++++--------------------- docs/setup.md | 106 +----------------------------------- 2 files changed, 86 insertions(+), 167 deletions(-) diff --git a/.env.example b/.env.example index 13ee5d4a97..d4ed63e170 100644 --- a/.env.example +++ b/.env.example @@ -1,33 +1,45 @@ -PLUGINS=all -DEFAULT_URL=http://localhost:3000 -SECRET_TOKEN={bundle exec rake secret} -RAILS_MIN_THREADS=5 -RAILS_MAX_THREADS=10 -CACHE_STORE=memory # use in-memory cache ... set to "memcached" to use memcached from localhost / MEMCACHIER_SERVERS env var - -# Required token to fetch commit diff / PR status / create tags etc +SECRET_TOKEN= # required, generate with `bundle exec rake secret` +CACHE_STORE=memory # required, use in-"memory" cache or "memcached" to use memcached from localhost / MEMCACHIER_SERVERS env var + +## Github token, required +# Personal access token that Samson uses to access project repositories, commits, files and pull requests. +# - Navigate to https://github.com/settings/tokens/new to generate a new personal access token +# - Choose scopes repo, read:org, user and then generate the token GITHUB_TOKEN= +# PLUGINS=all # chose which plugins you want to enable (see setup/plugins.md), can also opt-out by using "all,-slack" +# DEFAULT_URL= # absolute url to samson (used by the mailer), e.g. http://localhost:3000 + # EMAIL_DOMAIN= # optional, set to company.com to limit login only for people at Company # DEPLOY_TIMEOUT=3600 # optional, deploy timeout in seconds, defaults to 2 hours +# RAILS_MIN_THREADS=5 # +# RAILS_MAX_THREADS=10 # -## Auth with Github (optional) +## Login with Github +# Register a new OAuth application on https://github.com/settings/applications/new +# - "Homepage URL" is the same as DEFAULT_URL +# - "Authorization callback URL" is /auth/github/callback # AUTH_GITHUB=true # GITHUB_CLIENT_ID= # GITHUB_SECRET= # GITHUB_ORGANIZATION= # optional, users need to be member of this organization to sign up eg. 'zendesk' # GITHUB_ADMIN_TEAM= # optional, users in this team are made into admins eg. owners # GITHUB_DEPLOY_TEAM= # optional, users in this team are made into deployers eg. developers -# GITHUB_WEB_URL= # optional, replaces https://github.com -# GITHUB_API_URL= # optional, replaces https://api.github.com -# GITHUB_STATUS_URL= # optional, replaces https://status.github.com -## Auth with Google (optional) +## Login with Google +# - Create a new project on https://console.developers.google.com/project +# - Enter a name and a unique project id +# - click APIs & auth +# - Turn on Contacts API and Google+ API (they are needed by Samson to get email and avatar) +# - Click the Credentials link and then create a new Client ID +# - Set the Authorized JavaScript Origins to same as DEFAULT_URL +# - Set the Authorized Redirect URI to /auth/google/callback +# - Create the Client ID # AUTH_GOOGLE=true # GOOGLE_CLIENT_ID= # GOOGLE_CLIENT_SECRET= -## Auth with LDAP (optional) +## Login with LDAP # AUTH_LDAP=true # LDAP_TITLE= # eg. My LDAP Server} # LDAP_HOST=192.168.25.188 @@ -37,13 +49,16 @@ GITHUB_TOKEN= # LDAP_BINDDN=userldap # LDAP_PASSWORD=myldapsecret -## Auth with Gitlab (optional) +## Login with Gitlab # AUTH_GITLAB=true # GITLAB_APPLICATION_ID= # GITLAB_SECRET= # GITLAB_URL= # optional, replaces https://gitlab.com -## Auth with Bitbucket (optional) +## Login with Bitbucket +# - register a new OAuth customer on https://bitbucket.org/account/user/{username}/api +# - Set the Homepage URL to same as DEFAULT_URL +# - Set the Authorization callback URL to /auth/bitbucket/callback # AUTH_BITBUCKET=true # BITBUCKET_KEY= # BITBUCKET_SECRET= @@ -53,9 +68,14 @@ GITHUB_TOKEN= # SMTP_USER= # SMTP_PASSWORD= +## Github enterprise +# GITHUB_WEB_URL= # replaces https://github.com +# GITHUB_API_URL= # replaces https://api.github.com +# GITHUB_STATUS_URL= # replaces https://status.github.com + ## Keys to set to be able to rotate session key without breaking everything else see config/initializers/secret_token.rb -ATTR_ENCRYPTED_KEY={bundle exec rake secret} # optional -BADGE_TOKEN_BASE={bundle exec rake secret} # optional +# ATTR_ENCRYPTED_KEY= # generate with `bundle exec rake secret` +# BADGE_TOKEN_BASE= # generate with `bundle exec rake secret` ## Periodical tasks (cron substitute, see lib/samson/periodical.rb) # Possible tasks: @@ -70,49 +90,51 @@ BADGE_TOKEN_BASE={bundle exec rake secret} # optional PERIODICAL=stop_expired_deploys:60,remove_expired_locks:60,report_system_stats:60,report_process_stats:60,periodical_deploy:86400,cancel_stalled_builds:3600 ## Buddy Check feature: deploys to production require a buddy -# BUDDY_CHECK_FEATURE=1 # optional, enable -# BUDDY_CHECK_TIME_LIMIT=20 # optional, max minutes a deploy is pending -# BYPASS_EMAIL= # optional, email destinations that are alerted about buddy_check bypasses, comma separated -# BYPASS_DETAILS= # optional 'Some text explaining bypass procedure' +# BUDDY_CHECK_FEATURE=1 # enable +# BYPASS_EMAIL= # email destinations that are alerted about buddy_check bypasses, comma separated +# BYPASS_DETAILS= # 'Some text explaining bypass procedure' +# BUDDY_CHECK_TIME_LIMIT= # max minutes a deploy is pending, default: 20 ## StatsD reporting # STATSD_HOST=192.168.1.1 # STATSD_PORT=8125 -# DATADOG_TRACER=1 # optional, enable datadog APM tracer +# DATADOG_TRACER=1 # enable datadog APM tracer # PROJECT_CREATED_NOTIFY_ADDRESS=bobby-the-security-auditor@yourcompany.com # PROJECT_DELETED_NOTIFY_ADDRESS=bobby-the-security-auditor@yourcompany.com # if not set uses PROJECT_CREATED_NOTIFY_ADDRESS -# DEPLOY_GROUP_FEATURE=1 # optional, enable Environments and DeployGroups +# DEPLOY_GROUP_FEATURE=1 # enable Environments and DeployGroups -# GITHUB_HOOK_SECRET=abcdef # optional, verify github hooks are signed with webhook secret +# GITHUB_HOOK_SECRET=abcdef # verify github hooks are signed with webhook secret -# AIRBRAKE_API_KEY= # optional, report errors to airbrake +# AIRBRAKE_API_KEY= # report errors to airbrake -# optional, report deploys to Assertible +# report deploys to Assertible # ASSERTIBLE_SERVICE_KEY= # ASSERTIBLE_DEPLOY_TOKEN= -# FORCE_SSL=1 # optional, to require SSL +# FORCE_SSL=1 # to require SSL -# SESSION_EXPIRATION=3600 # optional, after how much time (seconds) to expire sessions, default: 1 month +# SESSION_EXPIRATION=3600 # after how much time (seconds) to expire sessions, default: 1 month -# ENV_WHITELIST=FOOBAR,BARFOO # optional, list of env values that should be passed to the command when deploying +# ENV_WHITELIST=FOOBAR,BARFOO # list of env values that should be passed to the command when deploying -# PROCESS_WHITELIST=puma,mysql # optional, keywords to filter out of running process reporting +# PROCESS_WHITELIST=puma,mysql # keywords to filter out of running process reporting -# MAX_CONCURRENT_JOBS=0 # optional, max number of concurrent jobs Samson will run. default: 0 (unlimited) +# MAX_CONCURRENT_JOBS=0 # max number of concurrent jobs Samson will run. default: 0 (unlimited) # HELP_LINK="#samson" # link to show in UI and error pages # RELEASE_TAG_IN_REPO_RETRIES=10 # how often to retry finding a tag after it is released to github -## NewRelic: optional report performance stats see https://docs.newrelic.com/docs/agents/ruby-agent/configuration/ruby-agent-configuration +## Plugin: NewRelic +# report performance stats see https://docs.newrelic.com/docs/agents/ruby-agent/configuration/ruby-agent-configuration # NEW_RELIC_LICENSE_KEY= # NEW_RELIC_APP_NAME=Samson # NEW_RELIC_LOG_FILE_PATH=STDOUT # # optional: show graphs during/after deploy +# https://docs.newrelic.com/docs/features/getting-started-with-the-new-relic-rest-api#setup # NEW_RELIC_API_KEY= ## Memcache: configure servers or we use localhost @@ -121,22 +143,23 @@ PERIODICAL=stop_expired_deploys:60,remove_expired_locks:60,report_system_stats:6 # MEMCACHIER_PASSWORD=password ## Docker -# DOCKER_FEATURE=1 # optional, docker support +# DOCKER_FEATURE=1 # docker support # DOCKER_REGISTRIES=https://user:pass@my.registry/some-namespace # required, where to push/pull your docker images # DOCKER_HOST= # e.g. tcp://my-docker-registry.example.com:2375 -# DOCKER_KEEP_BUILT_IMGS # optional. Set to 1 to keep built images for cache. Fills the disk so some cleanup machanism is needed -# DOCKER_READ_TIMEOUT=600 # optional. How long to wait on docker reads. -# DOCKER_FORCE_EXTERNAL_BUILD=1 # optional. Force docker to use images built externally. +# DOCKER_KEEP_BUILT_IMGS=1 # Set to 1 to keep built images for cache. Fills the disk so some cleanup machanism is needed +# DOCKER_READ_TIMEOUT=600 # how long to wait on docker reads. +# DOCKER_FORCE_EXTERNAL_BUILD=1 # force docker to use images built externally. # EXTERNAL_BUILD_WAIT=60 # how long to wait for external builds to arrive when deploying (checking every 5s) -# FLOWDOCK_API_TOKEN= # optional. only required for the flowdock integration user mention autocomplete in the buddy approval request form (when BUDDY_CHECK_FEATURE=1). Buddy approval notification would still work without this +## Plugin: flowdock +# FLOWDOCK_API_TOKEN= # Needed for the flowdock integration user mention autocomplete in the buddy approval request form (when BUDDY_CHECK_FEATURE=1). Buddy approval notification would still work without this -## Slack -# SLACK_API_TOKEN= # optional. only required for the slack integration user mention autocomplete in the buddy approval request form (when BUDDY_CHECK_FEATURE=1). Buddy approval notification would still work without this -# SLACK_CLIENT_ID= # optional, see plugins/slack_app/README.md -# SLACK_CLIENT_SECRET= # optional, see plugins/slack_app/README.md -# SLACK_VERIFICATION_TOKEN= # optional, see plugins/slack_app/README.md -# SLACK_GLOBAL_BUDDY_REQUEST="#" # send notifications for all buddy requests to this channel +## Plugin: Slack +# SLACK_API_TOKEN= # Needed for the slack integration user mention autocomplete in the buddy approval request form (when BUDDY_CHECK_FEATURE=1). Buddy approval notification would still work without this +# SLACK_CLIENT_ID= # see plugins/slack_app/README.md +# SLACK_CLIENT_SECRET= # see plugins/slack_app/README.md +# SLACK_VERIFICATION_TOKEN= # see plugins/slack_app/README.md +# SLACK_GLOBAL_BUDDY_REQUEST="#" # optional, send notifications for all buddy requests to this channel ## Export job cleanup ## EXPORT_JOB_DOWNLOADED_AGE determines how long a csv export job and file should @@ -158,22 +181,22 @@ PERIODICAL=stop_expired_deploys:60,remove_expired_locks:60,report_system_stats:6 ## pull request's title and body, only "http://z.atlassian.net/browse/KEY-123" ## would appear in the "JIRA Issues" tab). ## -# JIRA_BASE_URL= # optional, eg. https://jira.atlassian.net/browse/ +# JIRA_BASE_URL= # eg. https://jira.atlassian.net/browse/ ## Request access UI on users profile page -# REQUEST_ACCESS_FEATURE=1 # optional, enable request access link -# REQUEST_ACCESS_EMAIL_ADDRESS_LIST= # optional, space separated list of email addresses (managers mailing list, JIRA, etc.) +# REQUEST_ACCESS_FEATURE=1 # enable request access link +# REQUEST_ACCESS_EMAIL_ADDRESS_LIST= # space separated list of email addresses (managers mailing list, JIRA, etc.) # REQUEST_ACCESS_EMAIL_PREFIX= # optional, email subject prefix ## Secret storage -# SECRET_STORAGE_BACKEND= # optional, should be one of: Samson::Secrets::DbBackend (default) or Samson::Secrets::HashicorpVaultBackend -# SECRET_STORAGE_SHARING_GRANTS=true # optional, instead of sharing global secrets by default, access has to be granted -# SECRET_ENV_AS_ANNOTATIONS=true # optional, convert env vars that include secrets to annotations -# VAULT_PREFIX= # optional, what to prefix vault keys with if using Samson::Secrets::HashicorpVaultBackend - -## Kubernetes -# SECRET_PULLER_IMAGE=zendesk/samson_secret_puller:latest # optional, docker image for zendesk/samson_secret_puller -# KUBECONFIG=/home/kube/.kube/config # optional, used for database seeding +# SECRET_STORAGE_BACKEND= # should be one of: Samson::Secrets::DbBackend (default) or Samson::Secrets::HashicorpVaultBackend +# SECRET_STORAGE_SHARING_GRANTS=true # instead of sharing global secrets by default, access has to be granted +# SECRET_ENV_AS_ANNOTATIONS=true # convert env vars that include secrets to annotations +# VAULT_PREFIX= # what to prefix vault keys with if using Samson::Secrets::HashicorpVaultBackend + +## Plugin: Kubernetes +# SECRET_PULLER_IMAGE=zendesk/samson_secret_puller:latest # docker image for zendesk/samson_secret_puller +# KUBECONFIG=/home/kube/.kube/config # used for database seeding # KUBERNETES_LOG_TIMEOUT=20 # how long to wait for logs to appear in seconds # KUBERNETES_LOG_LINES=50 # how many lines of logs to show when a deploy fails # KUBERNETES_ALLOWED_VOLUME_HOST_PATHS=/data/ # prevent containers from mounting dangerous directories @@ -181,7 +204,7 @@ PERIODICAL=stop_expired_deploys:60,remove_expired_locks:60,report_system_stats:6 # KUBERNETES_SERVICE_PERSISTENT_FIELDS="metadata.labels.proxy,spec.foo" # fields to not override when updating services unless they are not set, does not support fields with . in their name like metadata.annotations.gcr.io/foo/bar # KUBERNETES_NO_CPU_LIMIT_ALLOWED=1 # allow users to chose to not have a cpu limit on their resources -## Jenkins +## Plugin: Jenkins ## Required for Jenkins Plugin - JENKINS_URL, JENKINS_USERNAME, JENKINS_API_KEY ## Required for JenkinsStatusChecker Plugin - JENKINS_URL, JENKINS_USERNAME, JENKINS_API_KEY, JENKINS_STATUS_CHECKER # JENKINS_URL= # server_url of jenkins @@ -194,15 +217,15 @@ PERIODICAL=stop_expired_deploys:60,remove_expired_locks:60,report_system_stats:6 # AUTOMATED_DEPLOY_FAILURE_EMAIL=foo@bar.com ## Gcloud -# GCLOUD_IMAGE_TAGGER=true # optional, enable image tagging -# GCLOUD_OPTIONS=--verbose # optional, options +# GCLOUD_IMAGE_TAGGER=true # enable image tagging # GCLOUD_PROJECT=foo-123 # GCLOUD_ACCOUNT=my-account +# GCLOUD_OPTIONS=--verbose # optional options -## Feature: Only admins can (un)lock stages which affect production. +## Only admins can (un)lock stages which affect production. # PRODUCTION_STAGE_LOCK_REQUIRES_ADMIN=1 -## Feature: Use LDAP_UID as user.external_id. +## Use LDAP_UID as user.external_id. # The default is to use the Distinguished Name for users.external_id. If your organization changes # any part of the DNs for any reason, this could cause any configured users to loose their current # configuration since it will be assumed to be a new user with a new external_id. This feature @@ -213,8 +236,8 @@ PERIODICAL=stop_expired_deploys:60,remove_expired_locks:60,report_system_stats:6 # https://github.com/omniauth/omniauth-ldap/blob/master/lib/omniauth/strategies/ldap.rb#L17 # USE_LDAP_UID_AS_EXTERNAL_ID=1 -## Feature: Rollbar error reporting +## Plugin: Rollbar error reporting # Report Samson's internal failures to Rollbar service -# ROLLBAR_ACCESS_TOKEN= # API token, required +# ROLLBAR_ACCESS_TOKEN= # API token # ROLLBAR_URL=https://api.rollbar.com # optional # ROLLBAR_WEB_BASE=https://rollbar.com # optional diff --git a/docs/setup.md b/docs/setup.md index 86708e8225..aab08c9b8c 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -53,111 +53,7 @@ To restart the server use `kill -USR1 ` which makes it restart without losi ## Settings -Set the following variables in your `.env` file or set them as environment variables in the shell you spawn the webserver from: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
KeyRequiredDescription
SECRET_TOKENYesfor Rails, generated during `bin/setup`
GITHUB_TOKENYesThis is a personal access token that Samson uses to access project repositories, commits, files and pull requests. -
    -
  • Navigate to https://github.com/settings/tokens/new to generate a new personal access token
    • -
  • Choose scope including repo, read:org, user and then generate the token
    • -
  • You should now have a personal access token to populate the .env file with
    • -
-
GITHUB_CLIENT_ID
GITHUB_SECRET		 - These settings are used if you want to allow users to login/authenticate with Github OAuth -
    -
  • Navigate to https://github.com/settings/applications/new and register a new OAuth application
    • -
  • Set the Homepage URL to http://localhost:3000
    • -
  • Set the Authorization callback URL to http://localhost:3000/auth/github/callback
    • -
  • You should now have Client ID and Client Secret values to populate the these with
    • -
-
DEFAULT_URLabsolute url to samson (used by the mailer), e.g. http://localhost:3000
GITHUB_ORGANIZATION
GITHUB_ADMIN_TEAM
GITHUB_DEPLOY_TEAM		Samson can use an organisation's teams to provide default roles to users authenticating with GitHub. -
    -
  • GITHUB_ORGANIZATION is the name of the organisation to read teams from, e.g. zendesk
    • -
  • Setting GITHUB_ADMIN_TEAM will allow any users part of the that team within the GITHUB_ORGANIZATION organization to have 'ADMINISTRATOR' permissions.
    • -
  • Setting GITHUB_DEPLOY_TEAM will allow any users part of the that team within the GITHUB_ORGANIZATION organization to have 'DEPLOYER' permissions.
    • -
- Other users will get 'VIEWER' permissions by default if part of this organization. -
GITHUB_WEB_URL
GITHUB_API_URL		Samson can use custom GitHub endpoints if, for example, you are using GitHub enterprise. -
    -
  • GITHUB_WEB_URL is used for GitHub interface links, e.g. compare screens, OAuth authorization
    • -
  • GITHUB_API_URL is used for GitHub API access
    • -
-
GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET		 - These settings are used if you want to allow users to login/authenticate with Google OAuth -
    -
  • Navigate to https://console.developers.google.com/project and create a new project
    • -
  • Enter a name and a unique project id
    • -
  • Once the project is provisioned, click APIs & auth
    • -
  • Turn on Contacts API and Google+ API (they are needed by Samson to get email and avatar)
    • -
  • Click the Credentials link and then create a new Client ID
    • -
  • Set the Authorized JavaScript Origins to http://localhost:3000
    • -
  • Set the Authorized Redirect URI to http://localhost:3000/auth/google/callback
    • -
  • Create the Client ID
    • -
- You should now have Client ID and Client secret values to populate the .env file with -
BITBUCKET_KEY
BITBUCKET_SECRET		 - These settings are used if you want to allow users to login/authenticate with Bitbucket OAuth -
    -
  • Navigate to https://bitbucket.org/account/user/{username}/api and register a new OAuth customer
    • -
  • Set the Homepage URL to http://localhost:3000
    • -
  • Set the Authorization callback URL to http://localhost:3000/auth/bitbucket/callback
    • -
  • You should now have Key and Secret values to populate the these with
    • -
-
NEW_RELIC_API_KEYYou may fill in using the instructions below if you would like a dynamic chart of response time and throughput during deploys. - https://docs.newrelic.com/docs/features/getting-started-with-the-new-relic-rest-api#setup
MAX_CONCURRENT_JOBSThe maximum number of concurrent jobs Samson will run. If a user tried to create a deployment that cause Samson to surpass this limit it will be added to a queue. Setting to 0, or not including all will allow unlimited concurrent jobs
+Set environment variables in your `.env` file, see `.env.example` for documentation on what is required/available. ## Production assets