This guide assumes you are installing the Console on the latest, EKS-based (v3) Rack. If you want to install your Console on an ECS-based v2 Rack, there are a couple of notes below of extra steps to perform.
This step is only necessary if you're using AWS Gov Cloud. Regular AWS Cloud installation doesn't require a local rack specifically.
Create a new rack locally using your AWS Gov Cloud credentials
You can pass the same parameters as in the UI using the form key=value
$ convox rack install aws gov-rack region=us-gov-east-1
don't forget to pass the gov cloud region
$ git clone https://github.com/convox/console-app
You can use any name you like but this document will assume the name console.
$ convox apps create console
Convox will provide credentials for a private registry to access the Console images.
Substitute USERNAME and PASSWORD in this command to add the private registry to your Rack.
$ convox registries add enterprise.convox.com USERNAME PASSWORD
Create a new CloudFormation stack using the formation.json from this repository.
You can use any name you like but the rest of this document will assume the name console-resources.
You can do this easily via your AWS Web Console, uploading the formation.json at the appropriate stage, or using the aws cli:
$ aws cloudformation create-stack --stack-name console-resources --capabilities CAPABILITY_IAM --template-body file://formation.json
If you are using AWS GovCloud, you have to set the AwsArn parameter as aws-us-gov:
$ aws cloudformation create-stack --stack-name console-resources --capabilities CAPABILITY_IAM --parameters ParameterKey=AwsArn,ParameterValue=aws-us-gov --template-body file://formation.json
Wait for this stack to fully complete (can take ~10 minutes to complete depending on AWS).
You will need to have jq installed if you don't already.
$ bin/export-env console-resources | convox env set -a console
Convox will provide you a license key for your Console.
$ convox env set -a console LICENSE_KEY=...
Decide on a custom domain for your Console. These instructions will assume console.example.org.
Create an SSL certificate for your application. You can use convox certs import to load a certificate
that you create manually or you can use the Rack's built-in certificate generator.
$ convox certs generate console.example.org
If you use the automatic certificate generation you will need to accept the certificate validation email that will be sent to the DNS administrator of the domain.
Create a CNAME record for this domain to point at the Router attribute shown when you run convox rack.
$ convox env set -a console HOST=console.example.org
For v3 rack
$ bin/export-env-v3 console | convox env set -a console
For v2 rack
$ bin/export-env-v2 console | convox env set -a console
To make the Console only accessible inside the VPC, you will need to set Internal mode.
$ convox env set -a console INTERNAL=true
(If you are deploying your Console app to an older v2 Rack, this will require your Rack to have the parameter Internal=Yes set)
Deploy the application contained in this repository.
$ convox deploy -a console
$ convox apps params set RackUrl=Yes -a console
If you'd like to use the GitHub, GitLab, or Slack integrations in your private Console you will need to create your own OAuth applications for each service.
Use the following callback URL(s) for each service:
| Provider | Callback URL(s) |
|---|---|
| Github | https://$host/ |
| Gitlab | https://$host/integrations/authorize/gitlabhttps://$host/integrations/reauthorize |
| Slack | https://$host/integrations/authorize/slack |
Once created, set the appropriate environment variables on your Console application:
$ convox env set -a console GITHUB_CLIENT_ID=... GITHUB_CLIENT_SECRET=...
$ convox env set -a console GITLAB_CLIENT_ID=... GITLAB_CLIENT_SECRET=...
$ convox env set -a console SLACK_CLIENT_ID=... SLACK_CLIENT_SECRET=...
If you're using GitHub, you'll need to set a random webhook secret:
$ convox env set -a console GITHUB_WEBHOOK_SECRET=...
If you'd like to use GitHub Enterprise, you'll also need to set the host:
$ convox env set -a console GITHUB_ENTERPRISE_CLIENT_ID=... GITHUB_ENTERPRISE_CLIENT_SECRET=... GITHUB_ENTERPRISE_HOST=github.mycompany.org
Promote the environment changes
$ convox releases promote -a console
You can provide credentials for a secure (TLS) LDAP endpoint to use for authentication.
$ convox env set -a console AUTHENTICATION=ldap
$ convox env set -a console LDAP_ADDR=auth.example.org:636 LDAP_BIND=uid=%s,dc=example,dc=org
Set LDAP_BIND to a full bind string where %s will be substituted for the user's email address.
If your LDAP server does not have a valid certificate issued by a known CA, you can disable certificate validation:
$ convox env set -a console LDAP_VERIFY=no
Promote the environment changes
$ convox releases promote -a console
You can provide configuration details to use SAML for authentication.
$ convox env set -a console AUTHENTICATION=saml
$ convox env set -a console SAML_METADATA=https://login.microsoftonline.com/common/FederationMetadata/2007-06/FederationMetadata.xml
SAML_METADATA should be set to the metadata endpoint for your SAML Identity Provider. This varies from provider to provider so please check your documentation from them.
Promote the environment changes
$ convox releases promote -a console
First, go to the console UI, register a new user and name your organization.
Then go to the Account Tab and click "Reset CLI Key" - run the output command in your terminal.
Now, run the following command
$ convox rack mv gov-rack orgName/gov-rack
Where gov-rack is the name of the rack you created and orgName the name of the organization you created in the console.
Go to the "Racks" tab and confirm your rack was moved.
Note that this step is only necessary once.
In the Console, go to "Integrations" and click the "+" next to "Runtime".
Select "AWS Gov Web Services" and click "Launch Stack". This will take you to the AWS CloudFormation UI.
Before creating the stack, make sure to check the box near "I acknowledge that AWS CloudFormation might create IAM resources.".
This stack is creating an IAM Role that the console will use to make changes to rack resources on your behalf.
Wait 1-2 minutes and refresh the Integrations UI to confirm the integration was installed
You can now use this Runtime to create additional racks directly from the console.
This step is only necessary for racks you move into the console.
Go to the "Racks" section, click the blue cog icon near your moved rack and in the "Runtime" dropdown, select your newly created Integration. Click "Apply Changes"
This step is only necessary for racks you move into the console.
Follow the steps in our docs - Moving an AWS Rack section to give the console role permission to access the EKS rack cluster.
To update the rack to a new version, first make sure to update the Cloud Formation stack. If you used a custom value for any of the stack parameters, make sure to include them in the cf update command. You can check the "Parameters" section of the CloudFormation stack if you're not sure. E.g: if you have used a custom value in TablePrefix:
aws cloudformation update-stack --stack-name change-me --capabilities CAPABILITY_IAM --parameters ParameterKey=TablePrefix,UsePreviousValue=true --template-body file://formation.jsonAfter the stack updates successfully, export the values to your console app:
Warning
If running a very old version of the console, it's possible that the bin/export-env script will output a RACK_KEY and SESSION_KEY values different than the ones you already set(you can get the current set values by running convox env -a console). If that's the case, just remove the variables from the bin/export-env output and set the other ones. You can also rollback the release if you forgot to remove them.
bin/export-env change-me | convox env set -a consoleAnd finally
convox deploy -a console