Sourcegraph AWS AMI instances

Sourcegraph Amazon Machine Images (AMIs) allow you to quickly deploy a production-ready Sourcegraph instance tuned to your organization's scale in just a few clicks.

Following these docs will provision the following resources:

• An EC2 instance running Sourcegraph
• A root EBS volume containing the EC2 instance OS, and Sourcegraph Docker images, with a default size of 50 GB
• An additional EBS volume for storing code and search indices, with a default of 500 GB, but should be customized during deployment

Instance Size Chart

Select an AMI according and instance type to the number of users and repositories you have using this table. If you fall between two sizes, choose the larger of the two.

For example, if you have 8,000 users with 80,000 repositories, your instance size would be L. If you have 1,000 users with 80,000 repositories, you should still go with size M.

Click here to see the completed list of AMI IDs published in each region.

The default AMI username is ec2-user.

Deploy Sourcegraph

1. In the instance size chart, click the link for the AMI that matches your deployment size
2. Choose Launch instance from AMI
3. Name your instance
4. Select an instance type according to the sizing chart
5. Key pair (login): Create a new Key Pair, or select an existing one from your AWS account for connecting to your instance via SSH (this may be required in the event you need support)
6. Network settings: Consult with your networking team for appropriate settings in your environment. To get started with a basic PoC instance (without production code), directly exposed to the internet:
   • Under "Auto-assign public IP" select "Enable"
   • Select a Security Group for the instance, or create one with rules appropriate to your needs:
     • Allow HTTPS from the internet: port range 443, source 0.0.0.0/0, ::/0
     • Allow HTTP traffic from the internet: port range 80, source 0.0.0.0/0, ::/0
     • Allow SSH from your WAN IP: port range 22, source <your WAN IP>/32
   • NOTE: Do not leave SSH open to the public internet.
   • NOTE: We highly recommend deploying an Application Load Balancer in front of your instance, and adjusting / removing these rules accordingly.
7. Configure storage:
   • Root Volume: 50GB
   • EBS Volume: 500GB - this should be at least 25-50% more than the size of all your repositories on disk; you may check your GitHub / Bitbucket / GitLab instance's disk usage, and leave yourself a margin for growth
8. Click Launch instance, and navigate to the public IP address in your browser; look for the IPv4 Public IP address in your EC2 instance's details page under the Description panel

Once the instance has started, please allow ~5 minutes for Sourcegraph to initialize. During this time you may observe a 404 page not found response.

To configure SSL, and lock down the instance from the public internet, see the networking section.

Executors

Executors are supported using native kubernetes executors.

Executors support auto-indexing and server-side batch changes.

To enable executors you must do the following:

1. Connect to the AMI instance using ssh
2. Run cd /home/ec2-user/deploy/install/
3. Replace the placeholder executor.frontendPassword in override.yaml
4. Run the following command to update the executor

SHELL
helm upgrade -i -f ./override.yaml --version "$(cat /home/ec2-user/.sourcegraph-version)" executor ./sourcegraph-executor-k8s-charts.tgz

1. Add the following to the site-admin config using the password you chose previously

SHELL
"executors.accessToken": "<exector.frontendPassword>",
"executors.frontendURL": "http://sourcegraph-frontend:30080",
"codeIntelAutoIndexing.enabled": true

1. Check Site-Admin > Executors > Instances to verify the executor connected successfully. If it does not appear try reboot the instance

To use server-side batch changes you will need to enable the native-ssbc-execution feature flag.

Networking

We suggest using an AWS Application Load Balancer (ALB) to manage HTTPS connections to Sourcegraph. This makes managing SSL certificates easy.

Creating an AWS Load Balancer

1. Request a certificate for the domain name in AWS Certificate Manager.
2. Create a target group for HTTPS Port 443 that links to the instance's Port 443.
3. Create a new subnet inside the instance VPC.
4. Create a new Application Load Balancer via AWS Load Balancers.

Step 1: Request certificate

Open the AWS Certificate Manager console to Request a certificate:

• Domain names: Fully qualified domain name: your domain
• Select validation method: DNS validation—recommended

After the certificate has been created, you will need to attach the CNAME name and CNAME values to your DNS.

Follow the steps below to attach the CNAME to your DNS if your DNS is hosted in AWS route 53:

1. Click Create record in route 53 in the certificate dashboard.
2. Select the DNS you would like to attach the certificate to.
3. Click Create records once you have verified the information is correct.
4. Wait ~30 minutes before the validation is completed.

Step 2: Create a target group

1. Click Create a target group on your EC2 Target groups dashboard
   • Choose a target type: Instance
   • Target group name: YOUR-TARGETGROUP-NAME
   • Protocol: HTTPS
   • Port: 443
   • VPC: Select the VPC where your instance is located.
   • Protocol version: HTTP2
   • Health checks: Use Default
2. Click Include as pending below

Step 3: Create subnets

Click Create subnet in your VPC subnets dashboard:

• VPC ID: Selected the VPC that the instance is in.
• Subnet name: name the subnet.
• Availability Zone: select an availability zone that is different from the current zone.
• Click Create subnet

Step 4: Create an Application Load Balancer

1. Open your EC2 Load Balancers dashboard to Create Load Balancer.
2. Choose Application Load Balancer as the Load balancer types using the following configurations:

• Basic configuration
  • Load balancer name: YOUR-LOAD-BALANCER-NAME
  • Scheme: Internet-facing
  • IP address type: IPv4
• Network mapping
  • VPC: Selected the VPC that the instance is in.
  • Mapping: Select two subnets associated with the selected VPC.
• Security groups
  • Security groups: Make sure only the security group associated with the instance is selected.
• Listeners and routing
  • Protocol: HTTPS
  • Port: 443
  • Default action: Select the HTTPS target group created for the instance.

Securing Your Instance

1. Configure user authentication (SSO, SAML, OpenID Connect, etc.) to give users of your Sourcegraph instance access to it.

Now that your instance is confirmed to be working, and you have HTTPS working through an Application Load Balancer, we recommend securing your Sourcegraph instance further by modifying the security group rules to prevent access from the public internet.

Upgrade

Please take time to review the following before proceeding with the upgrades:

• Changelog
• Update policy
• Update notes
• Multi-version upgrade procedure

Step 1: Stop the current instance

1. Stop your current Sourcegraph AMI instance
   • Go to the EC2 console for your instance
   • Click Instance State to Stop Instance
2. Detach the non-root data volume (Device name: /dev/sdb/)
   • Go to the Storage section in your instance console
   • Find the volume with the device name /dev/sdb
   • Select the volume, then click Actions to Detach Volume
   • Give the volume a name for identification purposes
3. Make a note of the VPC name

Step 2: Launch a new instance

1. Launch a new Sourcegraph instance from an AMI with the latest version of Sourcegraph
2. Name the instance
3. Select the appropriate instance type
4. Under Key Pair

• Select the Key Pair used by the old instance

5. Under Network settings
   • Select the Security Group used by the old instance
6. Under Configure storage

• Remove the second EBS volume

7. After reviewing the settings, click Launch Instance
8. Attach the detached volume to the new instance
   • Go to the Volumes section in your EC2 Console
   • Select the volume you've detached earlier
   • Click Actions > Attach Volume
9. On the Attach volume page:

• Instance: select the new Sourcegraph AMI instance
• Device name: /dev/sdb

10. Reboot the new instance

You can terminate the stopped Sourcegraph AMI instance once you have confirmed the new instance is up and running.

Downgrade

Please refer to the upgrade procedure above if you wish to roll back your instance.

Backups

We strongly recommend you take snapshots of the entire EBS volume on an automatic, scheduled basis.

Additional Resources

• Increase the size of an Amazon EBS volume on an EC2 instance
• Change the instance type