Install Sourcegraph on Amazon Web Services (AWS)
⚠️ We recommend new users use our AWS AMI or script-install instructions, which are easier and offer more flexibility when configuring Sourcegraph. Existing customers can reach out to our Customer Engineering team [email protected] if they wish to migrate to these deployment models.
This guide will take you through how to deploy Sourcegraph with Docker Compose to a single EC2 instance on Amazon Web Services (AWS).
RECOMMENDED Deploy a Sourcegraph instance with an AWS AMI or AWS One-Click.
Configure
Click Launch Instance from the EC2 dashboard, then fill in the following values for each section:
Name and tags
- Name your instance
Application and OS Images
-
Select Amazon Linux in the Quick Start tab
-
Select Amazon Linux 2 AMI (HVM), SSD Volume Type under Amazon Machine Image (AMI)
Instance type
- Select an appropriate instance type using our resource estimator as reference
Key pair (login)
- Create a new key pair for your instance, or choose an existing key pair from the drop down list
Network settings
-
Click
Edit
in the header to enable Auto-assign Public IP -
Under Firewall (security group) , create or select existing security group with the following settings:
- Allow SSH traffic from Anywhere
- Allow HTTPs traffic from the internet
- Allow HTTP traffic from the internet
Configure storage
-
Click Add New Volume to add an additional EBS volume for storing data
-
Click Advanced in the header to update the following settings for the new Custom Volume:
Storage Type
: EBSDevice name
:/dev/sdb
Volume Type
:gp3
(General Purpose SSD)Size (GiB)
:250GB minimum
- Sourcegraph needs at least as much space as all your repositories combined take up
- Allocating as much disk space as you can upfront minimize the need for resizing your volume in the future
Delete on Termination
:No
Advanced details > User Data
Copy and paste the startup script below into the User Data textbox:
#!/usr/bin/env bash set -euxo pipefail ############################################################################### # ACTION REQUIRED: REPLACE THE URL AND REVISION WITH YOUR DEPLOYMENT REPO INFO ############################################################################### # Please read the notes below the script if you are cloning a private repository DEPLOY_SOURCEGRAPH_DOCKER_FORK_CLONE_URL='https://github.com/sourcegraph/deploy-sourcegraph-docker.git' DEPLOY_SOURCEGRAPH_DOCKER_FORK_REVISION='v5.2.5' ##################### NO CHANGES REQUIRED BELOW THIS LINE ##################### DEPLOY_SOURCEGRAPH_DOCKER_CHECKOUT='/home/ec2-user/deploy-sourcegraph-docker' DOCKER_COMPOSE_VERSION='1.29.2' DOCKER_DAEMON_CONFIG_FILE='/etc/docker/daemon.json' DOCKER_DATA_ROOT='/mnt/docker-data' EBS_VOLUME_DEVICE_NAME='/dev/sdb' EBS_VOLUME_LABEL='sourcegraph' # Install git yum update -y yum install git -y # Clone the deployment repository git clone "${DEPLOY_SOURCEGRAPH_DOCKER_FORK_CLONE_URL}" "${DEPLOY_SOURCEGRAPH_DOCKER_CHECKOUT}" cd "${DEPLOY_SOURCEGRAPH_DOCKER_CHECKOUT}" git checkout "${DEPLOY_SOURCEGRAPH_DOCKER_FORK_REVISION}" # Format (if unformatted) and then mount the attached volume device_fs=$(lsblk "${EBS_VOLUME_DEVICE_NAME}" --noheadings --output fsType) if [ "${device_fs}" == "" ] then mkfs -t xfs "${EBS_VOLUME_DEVICE_NAME}" fi xfs_admin -L "${EBS_VOLUME_LABEL}" "${EBS_VOLUME_DEVICE_NAME}" mkdir -p "${DOCKER_DATA_ROOT}" mount -L "${EBS_VOLUME_LABEL}" "${DOCKER_DATA_ROOT}" # Mount file system by label on reboot echo "LABEL=${EBS_VOLUME_LABEL} ${DOCKER_DATA_ROOT} xfs defaults,nofail 0 2" >> '/etc/fstab' umount "${DOCKER_DATA_ROOT}" mount -a # Install, configure, and enable Docker yum update -y amazon-linux-extras install docker systemctl enable --now docker sed -i -e 's/1024/262144/g' /etc/sysconfig/docker sed -i -e 's/4096/262144/g' /etc/sysconfig/docker usermod -a -G docker ec2-user # Install jq for scripting yum install -y jq ## Initialize the config file with empty json if it doesn't exist if [ ! -f "${DOCKER_DAEMON_CONFIG_FILE}" ] then mkdir -p $(dirname "${DOCKER_DAEMON_CONFIG_FILE}") echo '{}' > "${DOCKER_DAEMON_CONFIG_FILE}" fi ## Point Docker storage to mounted volume tmp_config=$(mktemp) trap "rm -f ${tmp_config}" EXIT cat "${DOCKER_DAEMON_CONFIG_FILE}" | jq --arg DATA_ROOT "${DOCKER_DATA_ROOT}" '.["data-root"]=$DATA_ROOT' > "${tmp_config}" cat "${tmp_config}" > "${DOCKER_DAEMON_CONFIG_FILE}" # Restart Docker daemon to pick up new changes systemctl restart --now docker # Install Docker Compose curl -L "https://github.com/docker/compose/releases/download/${DOCKER_COMPOSE_VERSION}/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose chmod +x /usr/local/bin/docker-compose curl -L "https://raw.githubusercontent.com/docker/compose/${DOCKER_COMPOSE_VERSION}/contrib/completion/bash/docker-compose" -o /etc/bash_completion.d/docker-compose # Start Sourcegraph with Docker Compose cd "${DEPLOY_SOURCEGRAPH_DOCKER_CHECKOUT}"/docker-compose docker-compose up -d --remove-orphans
Deploy
-
Click Launch Instance in the Summary Section on the right to launch the EC2 node running Sourcegraph.
-
In your web browser, navigate to the public IP address assigned to the EC2 node. (Look for the IPv4 Public IP value in your EC2 instance page under the Description panel.) It may take a few minutes for the instance to finish initializing before Sourcegraph becomes accessible.
You can monitor the setup process by SSHing into the instance to run the following diagnostic commands:
# Follow the status of the startup script tail -f /var/log/cloud-init-output.log # Once installation is completed, check the health of the "sourcegraph-frontend" container docker ps --filter="name=sourcegraph-frontend-0"
Upgrade
See the Docker Compose upgrade docs.
Storage and Backups
Data is persisted within a Docker volume as defined in the deployment repository. The startup script configures Docker using a daemon configuration file to store all the data on the attached data volume, which is mounted at /mnt/docker-data
, where volumes are stored within /mnt/docker-data/volumes
.
There are two, non-mutually-exclusive ways to back up data:
-
Snapshot the entire
/mnt/docker-data
EBS volume on an automatic, scheduled basis. -
RECOMMENDED Use AWS RDS for PostgreSQL instead of the Dockerized PostgreSQL instance included by default. All data from Sourcegraph is derivable from the data stored in this database. Note, however, that it may take awhile to reclone repositories and rebuild indices afresh. If you require a faster restoration process, we recommend also snapshotting the EBS volume.
Other resources
HTTP and HTTPS/SSL configuration Site Administration Quickstart