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.

Installation

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

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:3.43.2

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.

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:

# 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:

FROM sourcegraph/server:3.43.2

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:

Create files at $HOME/.sourcegraph/config/ssh/config, $HOME/.sourcegraph/config/ssh/known_hosts, etc., on the host machine as desired to configure SSH.
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:

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).
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 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:3.43.2

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 user@host 0/0

Environment variables

Add the following to your docker run command:

docker run [...]
-e (YOUR CODE)
sourcegraph/server:3.43.2

Operation

Access the database

Get the Docker container ID for Sourcegraph:

docker ps
CONTAINER ID        IMAGE
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;

Upgrade

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 details of the latest release via the changelog.

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.

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.
```
--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).

Install Docker for Windows
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:3.43.2

Low resource environments

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

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.

Insiders build

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

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.