update deployment guide

.env.template

@@ -7,8 +7,11 @@ SITE_ADDRESS=
 # The domain name to use for the gateway service in the production compose stack
 GATEWAY_SITE_ADDRESS=
 
-# The port to listen on
+# The ports to listen on
 APP_PORT=5500
+PLAYGROUND_PORT=3750
+GATEWAY_PORT=3500
+
 # The Docker release to use (latest = stable)
 RELEASE_CHANNEL=main
 # The MongoDB version to use

README.md

@@ -28,39 +28,26 @@
 
 ![license](https://img.shields.io/github/license/DouglasNeuroInformatics/OpenDataCapture)
 ![version](https://img.shields.io/github/package-json/v/DouglasNeuroInformatics/OpenDataCapture)
+![build](https://github.com/DouglasNeuroInformatics/OpenDataCapture/actions/workflows/build.yaml/badge.svg)
 
-<!-- ![build](https://github.com/DouglasNeuroInformatics/OpenDataCapture/actions/workflows/build.yaml/badge.svg) -->
 <!-- [![codecov](https://codecov.io/gh/DouglasNeuroInformatics/OpenDataCapture/branch/main/graph/badge.svg?token=XHC7BY6PJ1)](https://codecov.io/gh/DouglasNeuroInformatics/OpenDataCapture) -->
 
 </div>
 <hr />
 
 ## About
 
-Open Data Capture is an integrated suite of applications tailored for the continuous and longitudinal collection of both clinical and research data. This platform is anchored on a few foundational principles:
+Open Data Capture is a web-based platform designed for continuous clinical data collection. Designed with clinician-researchers in mind, the platform enables both remote and in-person evaluations, encompassing a range of applications — from patient questionnaires completed at home to interactive memory tasks conducted in clinical settings. The platform is designed with a robust security framework, ensuring that all collected data is securely stored in a structured, standardized manner. It offers an intuitive, user-friendly interface to filter the stored data according to various criteria. Once filtered, the data can be used to generate dynamic graphs and tables, or exported for research purposes.
 
-- Versatility in Instruments: Whether it's surveys, clinical questionnaires, interactive tasks, or neuroimaging data, our platform can handle it all under the umbrella of a generic instrument.
-- User-Friendly Design: Designed with the user in mind, its intuitive interface ensures that even those without specialized knowledge can navigate and utilize the platform with ease.
-- Streamlined Deployment: With our one-liner deployment solution, leverage Docker Compose for a hassle-free, automated setup.
+## Quick Start
 
-## Deployment
+Assuming that Docker and Docker Compose are already installed on your system, you can deploy an instance of Open Data Capture using the following command:
 
-### Download Repository
-
-```shell
-git clone https://github.com/DouglasNeuroInformatics/OpenDataCapture
-cd OpenDataCapture
-```
-
-### Launch Application
-
-```shell
-./scripts/generate-env.sh
-docker compose up -d
-docker compose exec mongo mongosh --eval "rs.initiate({_id: 'rs0', members: [{_id: 0, host: 'localhost:27017'}]});"
+```sh
+./scripts/generate-env.sh && docker compose up -d
 ```
 
-By default, the application will run on port 5500. So, navigate to `http://localhost:5500` in your browser and you should be greeted with the setup screen.
+By default, the application will run on port 5500. So, navigate to `http://localhost:5500` in your browser and you should be greeted with the setup screen. After getting started, we highly recommend reading our [deployment guide](http://localhost:4000/en/tutorials/deployment/) for additional information on how to configure Open Data Capture to best meet the needs of your organization.
 
 ## Contribution
 

apps/outreach/src/styles/starlight-custom.css

@@ -306,3 +306,7 @@
 .tab > a {
   padding: 0.5rem 1.5rem !important;
 }
+
+.underline {
+  text-decoration: underline;
+}

docker-compose.yaml

@@ -48,7 +48,7 @@ services:
       context: .
       dockerfile: ./apps/gateway/Dockerfile
     ports:
-      - '3500:80'
+      - ${GATEWAY_PORT}:80
     expose:
       - 80
     environment:
@@ -60,7 +60,7 @@ services:
       context: .
       dockerfile: ./apps/playground/Dockerfile
     ports:
-      - '3750:80'
+      - ${PLAYGROUND_PORT}:80
     expose:
       - 80
   web:

docs/en/2-tutorials/2.0-development-setup.mdx → docs/en/2-tutorials/2.0-development.mdx

@@ -1,6 +1,6 @@
 ---
-title: Development Setup
-slug: en/tutorials/development-setup
+title: Development
+slug: en/tutorials/development
 sidebar:
   order: 0
 ---

docs/en/2-tutorials/2.1-deployment.md

@@ -5,42 +5,125 @@ sidebar:
   order: 1
 ---
 
-:::caution[Warning]
-This section is out of date and does not reflect recent development advances. Until this section is updated, the source code is the only authoritative reference regarding this topic.
+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](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_web_server).
+- Ports 80 ([HTTP](https://developer.mozilla.org/en-US/docs/Web/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](https://developer.mozilla.org/en-US/docs/Learn/Common_questions/Web_mechanics/What_is_a_domain_name) and have the ability to modify its DNS records.
+- You have installed [Docker and Docker Compose](https://docs.docker.com/) on your server (understanding how to use Docker is not required)
+
+:::note[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](https://www.digitalocean.com/).
 :::
 
-Welcome to our deployment guide! This resource is designed to be accessible for users with varying levels of technical expertise.
+### Steps
 
-### Server Configuration
+#### Step 1: Install HTTP Server
 
-Before continuing, please ensure the following:
+First, you will need to setup an HTTP server (if you are unsure which to use, we recommend [Caddy](https://caddyserver.com/)). Follow the instructions for installing the server of your choice. If you are using Caddy, make sure it is running as a system service:
 
-- You have root access on a Linux-based server
-- Ports 80 and 443 are exposed to the internet
-- You own a domain name and have appropriately configured the DNS records
+```sh
+systemctl status caddy
+```
 
-### Docker
+Regardless of which server you choose, it should be responding to HTTP requests:
 
-Our deployment relies on Docker. Please ensure that you have Docker and Docker Compose installed on your server. For more details, please refer to the [official documentation](https://docs.docker.com/).
+```sh
+curl localhost:80
+```
 
-> **Note:** These instructions were written in August 2023 using Docker version 24.0.2 and Docker Compose version 2.18.1.
+#### Step 2: Configure the DNS Records
 
-### Setup
+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](https://en.wikipedia.org/wiki/Dynamic_DNS) service.
 
-Now that the application is running, you need to send an HTTP request to a special setup endpoint. This will allow you to create the first admin user and optionally, to setup some initial dummy data. Please be advised that this action can only be performed if the database is completely empty.
+For example, you might want to host the core platform on <span class="underline">myplatform.com</span>, with the gateway hosted on <span class="underline">gateway.myplatform.com</span>.
 
-```shell
-SITE_ADDRESS=localhost:80
-curl --request POST \
-  --url $SITE_ADDRESS/api/v1/setup \
-  --header 'Content-Type: application/json' \
-  --data '{
-    "admin": {
-        "firstName": "Jane",
-        "lastName": "Doe",
-        "username": "admin",
-        "password": "Password123"
-    },
-    "initDemo": true
-}'
+| **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 <span class="underline">myplatform.com</span> 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:
+
+```sh
+cd /opt
 ```
+
+Then, clone the Open Data Capture repository:
+
+```sh
+git clone https://github.com/DouglasNeuroInformatics/OpenDataCapture.git
+```
+
+Navigate into the newly created directory:
+
+```sh
+cd OpenDataCapture
+```
+
+#### Step 4: Configuration
+
+All configuration of Open Data Capture is handled via [environment variables](https://en.wikipedia.org/wiki/Environment_variable), which are stored in a `.env` file. This file can be generated with the recommended defaults with the following command:
+
+```sh
+./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:
+
+```sh
+# 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:
+
+```sh
+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:
+
+```sh
+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:
+
+```sh
+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!