Docker Single Container Deployment

The Docker Single Container deployment type is a way to very quickly get an instance of Sourcegraph set up locally to experiment with many of its features. However, it is not recommended for a production instance, and has limitations depending on the OS you are deploying to, as well as the associated resources. See the troubleshooting section for additional information.

Code Insights is not supported in Single Container deployments. To try Code Insights you must deploy using Docker Compose or Kubernetes. Tracing is disabled by default, and if you intend to enable it, you will have to deploy and configure the OpenTelemetry Collector. The Single Container deployment does not ship with this service included. It is strongly recommended to use one of the aforementioned deployment methods if tracing support is a requirement.

Installation

It takes less than a minute to run and install Sourcegraph using Docker:

SHELL
docker run
--publish 7080:7080 --publish 127.0.0.1:3370:3370 --rm
--volume ~/.sourcegraph/config:/etc/sourcegraph
--volume ~/.sourcegraph/data:/var/opt/sourcegraph
sourcegraph/server:5.6.2535

Once the server is ready (logo is displayed in the terminal), navigate to the hostname or IP address on port 7080. Create the admin account, then you'll be guided through setting up Sourcegraph for code searching and navigation.

For next steps and further configuration options, review the high-level configuration items below, or visit the detailed configuration documentation.

WARNING: We do not recommend using this method for a production instance. If deploying a production instance, see our recommendations for how to choose a deployment type that suits your needs. We recommend Docker Compose for most initial production deployments.

Configuration

Configure exposed Sourcegraph port

Change the docker --publish argument to make it listen on the specific interface and port on your host machine. For example, docker run ... --publish 0.0.0.0:80:7080 ... would make it accessible on port 80 of your machine. For more information, see "Publish or expose port" in the Docker documentation.

The other option is to deploy and run Sourcegraph on a cloud provider. For an example, see the cloud installation section.

Git configuration and authentication

For single-container environments, upon the Sourcegraph Docker image container start, it copies all files from /etc/sourcegraph/{ssh,gitconfig,netrc} into its own $HOME directory, via the --volume /mnt/sourcegraph/config:/etc/sourcegraph in the docker run command.

For example, to mount a .gitconfig, create a file /mnt/sourcegraph/config/gitconfig on your host containing your configuration:

SHELL
# example .gitconfig

[url "example.url.com:"]
  insteadOf = "ssh://example.url.com"

Alternatively you can create a new Docker image which inherits from Sourcegraph and then mutates the environment:

DOCKERFILE
FROM sourcegraph/server:5.6.2535
 
COPY gitconfig /etc/gitconfig
COPY ssh /root/.ssh
RUN	find /root/.ssh -type f -exec chmod 600 '{}' ';'
RUN	find /root/.ssh -type d -exec chmod 700 '{}' ';'

This approach can also be used for sourcegraph/gitserver images in cluster environments.

Learn more about Git configuration and authentication.

SSH authentication (config, keys, known_hosts)

The container consults its own file system (in the standard locations) for SSH configuration, private keys, and known_hosts. Upon container start, it copies all files from /etc/sourcegraph/ssh into its own $HOME/.ssh directory.

To provide SSH authentication configuration to the container, assuming you're using the default --volume $HOME/.sourcegraph/config:/etc/sourcegraph, follow these steps:

1. Create files at $HOME/.sourcegraph/config/ssh/config, $HOME/.sourcegraph/config/ssh/known_hosts, etc., on the host machine as desired to configure SSH.
2. Start (or restart) the container.

To configure the container to use the same SSH as your user account on the host machine, you can also run cp -R $HOME/.ssh $HOME/.sourcegraph/config/ssh.

HTTP(S) authentication via netrc

The easiest way to specify HTTP(S) authentication for repositories is to include the username and password in the clone URL itself, such as https://user:password@example.com/my/repo. These credentials won't be displayed to non-admin users.

Otherwise, the container consults the $HOME/.netrc files on its own file system for HTTP(S) authentication. The .netrc file is a standard way to specify authentication used to connect to external hosts.

To provide HTTP(S) authentication, assuming you're using the default --volume $HOME/.sourcegraph/config:/etc/sourcegraph, follow these steps:

1. Create a file at $HOME/.sourcegraph/config/netrc on the host machine that contains lines of the form machine example.com login alice password mypassword (replacing example.com, alice, and mypassword with the actual values).
2. Start (or restart) the container.

Expose debug port

This is required to collect debug data.

The docker run command for single-container Sourcegraph needs an additional publish flag to expose the debug port:

SH
$ docker run --publish 7080:7080 --publish 127.0.0.1:3370:3370 --publish 127.0.0.1:6060:6060 --rm --volume ~/.sourcegraph/config:/etc/sourcegraph --volume ~/.sourcegraph/data:/var/opt/sourcegraph sourcegraph/server:5.6.2535

If Sourcegraph is deployed to a remote server, then access via an SSH tunnel using a tool such as sshuttle is required to establish a secure connection. To access the remote server using sshuttle from your local machine:

SH
$ sshuttle -r user@host 0/0

Environment variables

Add the following to your docker run command:

SH
$ docker run [...]
-e (YOUR CODE)
sourcegraph/server:5.6.2535

Operation

Access the database

NOTE: To execute an SQL query against the database without first creating an interactive session (as below), append --command "SELECT * FROM users;" to the docker container exec command.

Get the Docker container ID for Sourcegraph:

SH
$ docker ps
CONTAINER ID        IMAGE
d039ec989761        sourcegraph/server:VERSION

Open a PostgreSQL interactive terminal:

SH
$ docker container exec -it d039ec989761 psql -U postgres sourcegraph

Run your SQL query:

SQL
SELECT * FROM users;

Upgrade

Standard upgrades

A standard upgrade occurs between two minor versions of Sourcegraph. If you are looking to jump forward several versions, you must perform a multi-version upgrade instead.

Before upgrading:

• Read our update policy to learn about Sourcegraph updates.
• Find the relevant entry for your update in the update notes for single-container Sourcegraph with Docker.

To update, just use the newer sourcegraph/server:N.N.N Docker image (where N.N.N is a patch or single minor release away your current version) in place of the older one, using the same Docker volumes. Your server's data will be migrated automatically if needed. You can always find the version number details of the latest release via the changelog.

Multi-version upgrades

A multi-version upgrade is a downtime-incurring upgrade from version 3.20 or later to any future version. Multi-version upgrades will run both schema and data migrations to ensure the data available from the instance remains available post-upgrade.

NOTE: It is highly recommended to take an up-to-date snapshot of your databases prior to starting a multi-version upgrade. The upgrade process aggressively mutates the shape and contents of your database, and undiscovered errors in the migration process or unexpected environmental differences may cause an unusable instance or data loss.

We recommend performing the entire upgrade procedure on an idle clone of the production instance and switch traffic over on success, if possible. This may be low-effort for installations with a canary environment or a blue/green deployment strategy.

If you do not feel confident running this process solo, contact customer support team to help guide you thorough the process.

Before performing a multi-version upgrade:

• Read our update policy to learn about Sourcegraph updates.
• Find the entries that apply to the version range you're passing through in the update notes for Sourcegraph with Docker Single Container.

To perform a multi-version upgrade on a Sourcegraph instance running on Docker Single Container:

1. Stop the running Sourcegraph container via docker stop [CONTAINER].
2. Start a temporary Postgres container on top of the Postgres data directory used by the old sourcegraph/server image. This Postgres instance will be used by the following upgrade migration. If using an external database, the database is already accessible from the migrator so no action is needed. Otherwise, start the new Postgres container by following the steps described below.
3. Follow the instructions on how to run the migrator job in Docker to perform the upgrade migratiohn. For specific documentation on the upgrade command, see the command documentation. The following specific steps are an easy way to run the upgrade command:

SH
$ docker run \
  --rm \
  --name migrator_${SG_VERSION} \
  -e PGHOST='pgsql' \
  -e PGPORT='5432' \
  -e PGUSER='sg' \
  -e PGPASSWORD='sg' \
  -e PGDATABASE='sourcegraph' \
  -e PGSSLMODE='disable' \
  -e CODEINTEL_PGHOST='pgsql' \
  -e CODEINTEL_PGPORT='5432' \
  -e CODEINTEL_PGUSER='sg' \
  -e CODEINTEL_PGPASSWORD='sg' \
  -e CODEINTEL_PGDATABASE='sourcegraph-codeintel' \
  -e CODEINTEL_PGSSLMODE='disable' \
  -e CODEINSIGHTS_PGHOST='pgsql' \
  -e CODEINSIGHTS_PGPORT='5432' \
  -e CODEINSIGHTS_PGUSER='postgres' \
  -e CODEINSIGHTS_PGPASSWORD='password' \
  -e CODEINSIGHTS_PGDATABASE='postgres' \
  -e CODEINSIGHTS_PGSSLMODE='disable' \
  -e CODEINTEL_PG_ALLOW_SINGLE_DB=true \
  sourcegraph/migrator:v${SG_VERSION} \
  upgrade --from=${CURRENT_SG_VERSION} --to=${SG_VERSION}

It is recommended to also add the --dry-run flag on a trial invocation to detect if there are any issues with database connection, schema drift, or mismatched versions that need to be addressed.

After this container exits successfully, the remaining infrastructure can now be updated. All temporary containers can be stopped, and the Docker invocation for your sourcegraph/server container can be updated to use the new target version.

Running temporary Postgres containers

Mounting a Postgres container on top of the data directory used by sourcegraph/server will allow us to access and migrate the data in-place without having running services interfere.

Let ${PATH} be the directory mounted into /var/opt/sourcegraph of your instance. This mount contains the Postgres data directory inside of the container.

For example, ${PATH} is ~/.sourcegraph/data in -v ~/.sourcegraph/data:/var/opt/sourcegraph.

SH
$ docker run --rm -it \
  -v ${PATH}/postgresql:/data/pgdata-${PG_VERSION} \
  -u 70 \
  -p 5432:5432 \
  --entrypoint bash \
  sourcegraph/postgres-${PG_VERSION_TAG}:${SG_VERSION} \
  -c 'echo "host all all 0.0.0.0/0 trust" >> /data/pgdata-${PG_VERSION}/pg_hba.conf && postgres -c l listen_addresses="*" -D /data/pgdata-${PG_VERSION}'

The version of this Postgres container is dependent on the version of the instance prior to upgrade.

Troubleshooting

If you get stuck or need help, file an issue, tweet (@sourcegraph) or email.

Mac Computers with Apple silicon

On Mac computers with Apple silicon, you’ll need to add an extra --platform linux/amd64 argument to your Docker command for correctly running and installing Sourcegraph.

File system performance on Docker for Mac

There is a known issue in Docker for Mac that causes slower than expected file system performance on volume mounts, which impacts the performance of search and cloning.

To achieve better performance, you can do any of the following:

• For better clone performance, clone the repository on your host machine and then add it to Sourcegraph Server.
• Try adding the :delegated suffix the data volume mount. Learn more.

  SH
  --volume ~/.sourcegraph/data:/var/opt/sourcegraph:delegated

Testing Sourcegraph on Windows

Sourcegraph can be tested on Windows 10 using roughly the same steps provided above, but data will not be retained after server restarts (this is due to a limitation of Docker on Windows).

1. Install Docker for Windows
2. Using a command prompt, follow the same installation steps provided above but remove the --volume arguments. For example by pasting this:

docker run --publish 7080:7080 --publish 127.0.0.1:3370:3370 --rm sourcegraph/server:5.6.2535

Low resource environments

To test Sourcegraph in a low resource environment you may want to disable some of the observability tools (Prometheus and Grafana).

Add -e DISABLE_OBSERVABILITY=true to your docker run command.

Starting in Postgres restore mode

In order to restore a Postgres backup, you need to start on an empty database and prevent all other Sourcegraph services from starting. You can do this by adding -e PGRESTORE=true to your docker run command. This will start only the Postgres system and allow you to perform a restore. Once it is done, remove that parameter from your docker command.

The database is only accessible from within the container. To perform a restore you will need to copy the required files to the container and then execute the restore commands from within the container using docker exec.

You can find examples of this procedure for docker-compose in our docker-compose migration docs.

Special instructions for RHEL, Fedora, CentOS and others

If you run Docker on an OS such as RHEL, Fedora, or CentOS with SELinux enabled, sVirt doesn't allow the Docker process to access ~/.sourcegraph/config and ~/.sourcegraph/data. In that case, you will see the following message:

Failed to setup nginx:failed to generate nginx configuration to /etc/sourcegraph: open /etc/sourcegraph/nginx.conf: permission denied.

To fix this, run:

mkdir -p ~/.sourcegraph/config ~/.sourcegraph/data && chcon -R -t svirt_sandbox_file_t ~/.sourcegraph/config ~/.sourcegraph/data

Reference

Cloud installation guides

Cloud specific Sourcegraph installation guides for AWS, Google Cloud and Digital Ocean.

• Install Sourcegraph with Docker on AWS
• Install Sourcegraph with Docker on Google Cloud
• Install Sourcegraph with Docker on DigitalOcean

Insiders build

To test new development builds of Sourcegraph (triggered by commits to main), change the tag to insiders in the docker run command.

WARNING: insiders builds may be unstable, so back up Sourcegraph's data and config (usually ~/.sourcegraph) beforehand.

SH
$ docker run --publish 7080:7080 --rm --volume ~/.sourcegraph/config:/etc/sourcegraph --volume ~/.sourcegraph/data:/var/opt/sourcegraph sourcegraph/server:insiders

To keep this up to date, run docker pull sourcegraph/server:insiders to pull in the latest image, and restart the container to access new changes.