Skip to content

Running OSDF Origin in a Container


Currently, the origin container only supports distribution of public data. If you would like to distribute private data requiring authentication, see the RPM installation guide.

The OSG operates the Open Science Data Federation (OSDF), which provides organizations with a method to distribute their data in a scalable manner to thousands of jobs without needing to pre-stage data across sites or operate their own scalable infrastructure.

Origins store copies of users' data. Each community (or experiment) needs to run one origin to export its data via the federation. This document outlines how to run such an origin in a Docker container.


The OSDF Origin was previously named "Stash Origin" and some documentation and software may use the old name.

Before Starting

Before starting the installation process, consider the following requirements:

  1. Docker: For the purpose of this guide, the host must have a running docker service and you must have the ability to start containers (i.e., belong to the docker Unix group).
  2. Network ports: The origin listens for incoming HTTP(S) and XRootD connections on port 1094.
  3. File Systems: The origin needs a host partition to store user data.
  4. Hardware requirements: We recommend that an origin has at least 1Gbps connectivity and 8GB of RAM.
  5. Host certificate: Required for authentication. See our host certificate documentation for instructions on how to request host certificates.
  6. Registration: Before deploying an origin, you must register the service in the OSG Topology

Configuring the Origin

In addition to the required configuration above (ports and file systems), you may also configure the behavior of your origin with the following variables using an environment variable file:

Where the environment file on the docker host, /opt/origin/.env, has (at least) the following contents, replacing <YOUR_RESOURCE_NAME> with the resource name of your origin as registered in Topology and <FQDN> with the public DNS name that should be used to contact your origin:


Providing a host certificate

The service will need a certificate for contacting central OSDF services and for authenticating connections.

Follow our host certificate documentation to obtain a host certificate and key. Then, volume-mount the host certificate to /etc/grid-security/hostcert.pem, and the key to /etc/grid-security/hostkey.pem.


You must restart the container whenever you renew your certificate in order for the services to pick up the new certificate. If you automate certificate renewal, you should automate restarts as well. For example, if you are using Certbot for Let's Encrypt, you should write a "deploy hook" as documented on the Certbot site.

Populating Origin Data

The OSDF namespace is shared by multiple VOs so you must choose a namespace for your own VO's data. When running an origin container, your chosen namespace must be reflected in your host partition.

For example, if your host partition is /srv/origin-public and the name of your VO is ASTRO, you should store the Astro VO's public data in /srv/origin-public/astro/. Then, when starting container, you will mount /srv/origin-public/ into /xcache/namespace in the container.

Running the Origin

It is recommended to use a container orchestration service such as docker-compose or kubernetes whose details are beyond the scope of this document. The following sections provide examples for starting origin containers from the command-line as well as a more production-appropriate method using systemd.

[email protected] $ docker run --rm --publish 1094:1094 \
             --volume <HOST PARTITION>:/xcache/namespace \
             --volume <HOST CERT>:/etc/grid-security/hostcert.pem \
             --volume <HOST KEY>:/etc/grid-security/hostkey.pem \
             --env-file=/opt/origin/.env \

Replacing <HOST PARTITION> with the host directory containing data that your origin should serve. See this section for details.


A container deployed this way will serve the entire contents of <HOST PARTITION>.

Running on origin container with systemd

An example systemd service file for the OSDF. This will require creating the environment file in the directory /opt/origin/.env.


This example systemd file assumes <HOST PARTITION> is /srv/origin-public, and the cert and key to use are in /etc/ssl/host.crt and /etc/ssl/host.key, respectively.

Create the systemd service file /etc/systemd/system/docker.stash-origin.service as follows:

Description=Origin Container

ExecStartPre=-/usr/bin/docker stop %n
ExecStartPre=-/usr/bin/docker rm %n
ExecStartPre=/usr/bin/docker pull opensciencegrid/stash-origin:3.6-release
ExecStart=/usr/bin/docker run --rm --name %n --publish 1094:1094 \
  --volume /srv/origin-public:/xcache/namespace \
  --volume /etc/ssl/host.crt:/etc/grid-security/hostcert.pem \
  --volume /etc/ssl/host.key:/etc/grid-security/hostkey.pem \
  --env-file /opt/origin/.env \


Enable and start the service with:

[email protected] $ systemctl enable docker.stash-origin
[email protected] $ systemctl start docker.stash-origin


You must register the origin before starting it up.

Validating Origin

To validate the origin please follow the validating origin instructions.

Getting Help

To get assistance, please use the this page or contact directly.

Back to top