Single-container Sourcegraph with Docker operations guides

Operations guides specific to managing single-container Sourcegraph with Docker installations.

Trying to deploy single-container Sourcegraph with Docker? Refer to our installation guide.


Before upgrading, refer to 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 the version number) 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 of the latest release at in the docker run command's image tag.

  • As a precaution, before updating, we recommend backing up the contents of the Docker volumes used by Sourcegraph.
  • If you need a HA deployment, use the Kubernetes cluster deployment option.
  • There is currently no automated way to downgrade to an older version after you have updated. Contact support for help.

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 ... 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 documentation to deploy to Google Cloud.

Access the database

Get the Docker container ID for Sourcegraph:

docker ps
d039ec989761        sourcegraph/server:VERSION

Open a PostgreSQL interactive terminal:

docker container exec -it d039ec989761 psql -U postgres sourcegraph

Run your SQL query:

SELECT * FROM users;

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:

# example .gitconfig

[url ""]
  insteadOf = "ssh://"

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

FROM sourcegraph/server:3.39.0

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:[email protected]/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 login alice password mypassword (replacing, 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:

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

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:

sshuttle -r [email protected] 0/0

Environment variables

Add the following to your docker run command:

docker run [...]