Deployment

Welcome to our deployment guide! Open Data Capture is designed to make deployment as easy as possible, even for users with minimal prior experience managing web servers. When background knowledge is assumed, we provide a reference link where you can learn about the topic in question before continuing.

Prerequisites

This guide assumes the following:

• You have administrative (root) privileges on a Linux-based server.
• Ports 80 (HTTP) and 443 (HTTPS) are exposed to the internet (refer to your cloud provider, or ISP if self-hosting, for more information).
• You own a domain name and have the ability to modify its DNS records.
• You have installed Docker and Docker Compose on your server (understanding how to use Docker is not required)

What is a Server?

A server is just a computer that provides resources to other computers over a network. Theoretically, you could use your laptop as a server, but if you are a beginner we recommend using a cloud provider, such as DigitalOcean.

Steps

Step 1: Install HTTP Server

First, you will need to setup an HTTP server (if you are unsure which to use, we recommend Caddy). Follow the instructions for installing the server of your choice. If you are using Caddy, make sure it is running as a system service:

systemctl status caddy

Regardless of which server you choose, it should be responding to HTTP requests:

curl localhost:80

Step 2: Configure the DNS Records

Next, refer to the instructions from your domain registrar to add A records pointing to your web server’s IP address. If you’re self-hosting, you might also need to set up a DDNS service.

For example, you might want to host the core platform on myplatform.com, with the gateway hosted on gateway.myplatform.com.

Type	Name	Value	TTL
A	@	192.168.1.1	Auto
A	gateway	192.168.1.1	Auto
CNAME	www	myplatform.com	Auto

Once this is complete, you should be able to access your site at myplatform.com as soon as the DNS changes have propagated.

Step 3: Download Application

With your web server up and running, the next step is to download and launch Open Data Capture itself. As root, navigate to the directory where you want to install Open Data Capture:

cd /opt

Then, clone the Open Data Capture repository:

git clone https://github.com/DouglasNeuroInformatics/OpenDataCapture.git

Navigate into the newly created directory:

cd OpenDataCapture

Step 4: Configuration

All configuration of Open Data Capture is handled via environment variables, which are stored in a .env file. This file can be generated with the recommended defaults with the following command:

./scripts/generate-env.sh

Now, this would be sufficient to launch the application, but we should configure a few more settings to enable HTTPS. Open .env and make the following changes:

# The domain names we configured earlier
SITE_ADDRESS=myplatform.com
GATEWAY_SITE_ADDRESS=gateway.myplatform.com

# The ports to listen on
APP_PORT=5500
GATEWAY_PORT=3500

For the purposes of this guide, we will leave the other settings as the default values. However, for an actual production server, refer to the comments in the generated .env file to learn about the available options.

Step 5: Launch Application

Now, you should be able to launch the Docker Compose stack:

docker compose up -d

Step 6: Configure Web Server

Now, with the application running on various ports, we need to configure our web server:

For example, if you are using Caddy, modify /etc/caddy/Caddyfile as follows:

myplatform.com {
  reverse_proxy localhost:5500
}

gateway.myplatform.com {
  reverse_proxy localhost:3500
}

After writing the changes, we need to restart caddy for them to take effect:

systemctl reload caddy

Step 7: Setup Your Instance

The final setup is to create an initial admin for your instance of the platform. To do this, simply open the new website in your browser and follow the instructions.

Once you see the login screen, your instance of Open Data Capture is fully configured. Congratulations!