Skip to content

Commit

Permalink
update docs for new env variable configuration
Browse files Browse the repository at this point in the history
  • Loading branch information
@buckhalt
buckhalt committed Oct 15, 2024
1 parent 9c2a4fe commit 186991a
Show file tree
Hide file tree
Showing 3 changed files with 81 additions and 78 deletions.
39 changes: 18 additions & 21 deletions apps/documentation/docs/fresco/deployment/advanced.en.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,26 +20,26 @@ If you are not already familiar with these technologies, we recommend following
</PrerequisitesSection>
</SummaryCard>



To assist users who have specialized hosting needs, we have created a Docker container which allows Fresco to be deployed across a variety of contexts, including institutional IT infrastructure, privately owned VPSs, and internal networks. This tutorial will guide you through the requirements of deploying Fresco using our docker image, and will outline the necessary steps.

<Tipbox danger>
Because of the nature of self-hosting Dockerized applications on cloud
infrastructure, you are responsible for the security and maintenance of your
own deployment! The Network Canvas project team has no access to
your data or infrastructure by design, and updates will not be automatically applied. This may leave your data at risk.
own deployment! The Network Canvas project team has no access to your data or
infrastructure by design, and updates will not be automatically applied. This
may leave your data at risk.
</Tipbox>

## Requirements for deploying Fresco

Fresco is a NextJS application, which uses Amazon S3 for storage of protocol assets and PostgreSQL for storage of interview and app data.

To deploy Fresco, you'll need:
- A host machine running Docker with at least 1gb of RAM and enough disk space to store your protocol assets and interview data. This machine must at a minimum accept connections from the Internet on port 443 to the `api/uploadthing` endpoint. This endpoint is used as a callback for uploads to Amazon S3.
- A domain name with a TLS certificate. Free certificates can be obtained via services such as LetsEncrypt. Fresco requires the use of HTTPS.
- A suitable PostgreSQL 16.x database. This can either be in the form of a commercial service such as PlanetScale or Neon, or a local container via Docker.
- A free UploadThing API key. This library provides a wrapper over Amazon S3. Details on obtaining a key are provided later in this article.

- A host machine running Docker with at least 1gb of RAM and enough disk space to store your protocol assets and interview data. This machine must at a minimum accept connections from the Internet on port 443 to the `api/uploadthing` endpoint. This endpoint is used as a callback for uploads to Amazon S3.
- A domain name with a TLS certificate. Free certificates can be obtained via services such as LetsEncrypt. Fresco requires the use of HTTPS.
- A suitable PostgreSQL 16.x database. This can either be in the form of a commercial service such as PlanetScale or Neon, or a local container via Docker.
- A free UploadThing API key. This library provides a wrapper over Amazon S3. Details on obtaining a key are provided later in this article.

## Environment Variables

Expand All @@ -52,16 +52,13 @@ Create an `.env` file somewhere on your host machine using the template below. T
# Optional environment variables
# -------------------

# If true, the app will not send anonymous analytics and error data. Defaults to false.
# If true, the app will not send anonymous analytics and error data. Defaults to false.
#DISABLE_ANALYTICS=

# -------------------
# Required environment variables
# -------------------

UPLOADTHING_SECRET=
UPLOADTHING_APP_ID=

POSTGRES_PRISMA_URL=
POSTGRES_URL_NON_POOLING=

Expand Down Expand Up @@ -120,7 +117,7 @@ To create an app on UploadThing:
# Optional environment variables
# -------------------

# If true, the app will not send anonymous analytics and error data. Defaults to false.
# If true, the app will not send anonymous analytics and error data. Defaults to false.
#DISABLE_ANALYTICS=

# -------------------
Expand All @@ -141,10 +138,10 @@ Fresco uses a PostgreSQL database to store protocol and interview data. You will

Fresco requires two connection strings to PostgreSQL:

| **Variable** | **Details** |
| ---------------------------- | ---------------------------------------- |
| **POSTGRES_PRISMA_URL** | A pooled connection URL for Prisma. Connection pooling allows for efficient re-use of connections, and avoids potential issues caused by large numbers of concurrent users. |
| **POSTGRES_URL_NON_POOLING** | A non-pooling connection URL for Prisma. This is primarily used for database migrations when upgrading. |
| **Variable** | **Details** |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **POSTGRES_PRISMA_URL** | A pooled connection URL for Prisma. Connection pooling allows for efficient re-use of connections, and avoids potential issues caused by large numbers of concurrent users. |
| **POSTGRES_URL_NON_POOLING** | A non-pooling connection URL for Prisma. This is primarily used for database migrations when upgrading. |

If you do not have a connection pooler such as PgBouncer, you can use the same connection string for both variables (although this may lead to database errors under heavy load).

Expand All @@ -157,7 +154,7 @@ Add your connection strings to the `.env` file:
# Optional environment variables
# -------------------

# If true, the app will not send anonymous analytics and error data. Defaults to false.
# If true, the app will not send anonymous analytics and error data. Defaults to false.
#DISABLE_ANALYTICS=

# -------------------
Expand Down Expand Up @@ -185,7 +182,7 @@ Add your URL to the `.env` file:
# Optional environment variables
# -------------------

# If true, the app will not send anonymous analytics and error data. Defaults to false.
# If true, the app will not send anonymous analytics and error data. Defaults to false.
#DISABLE_ANALYTICS=

# -------------------
Expand Down Expand Up @@ -278,7 +275,7 @@ For details on this process, refer to the [configuration and setup](./guide#conf

## Updating Fresco

To update Fresco, you can pull the latest image from the GitHub container registry and recreate your container.
To update Fresco, you can pull the latest image from the GitHub container registry and recreate your container.

```bash
docker pull ghcr.io/complexdatacollective/fresco:latest
Expand All @@ -291,4 +288,4 @@ If you are using Docker Compose, you can use the following command:

```bash
docker-compose up -d -f docker-compose.yml
```
```
106 changes: 49 additions & 57 deletions apps/documentation/docs/fresco/deployment/guide.en.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -61,47 +61,7 @@ To do this, ensure you have a GitHub account and are signed in, and then:
![](/assets/img/fresco-images/github-fork2.png)

Once you have completed this step, you will be redirected to your forked repository on GitHub. This copy of the Fresco code is now yours to deploy or modify as you wish.

## Create a storage bucket using UploadThing

Fresco uses a third-party service called 'UploadThing' to store media files, including protocol assets. In order to use this service, you need to create an account with UploadThing that will allow you to generate an API key that Fresco can use to securely communicate with it.

<Tipbox>

Your UploadThing account is unique to you, meaning that no one else will have access to the files stored in your instance of Fresco. For more information about UploadThing, please review the <a href="https://docs.uploadthing.com" target="_blank">UploadThing Docs</a>.

</Tipbox>

To create an app on UploadThing:

1. Go to <a href="https://uploadthing.com" target="_blank">uploadthing.com</a>.

2. Click **"Get started"**.

![Select "Get Started"](/assets/img/fresco-images/uploadthing1.png)

3. Sign in with Github.

4. Authorize UploadThing by clicking **"Authorize pingdotgg"**.

5. You will be prompted to navigate to your dashboard. From the dashboard Click **"Create a new app"**.

![Create a new app](/assets/img/fresco-images/uploadthing4.png)

6. Give your app a name and click **"Create App"**. Do not change the region.

![Create app](/assets/img/fresco-images/uploadthing5.png)

7. From your dashboard, navigate to the **"API Keys"** section from the sidebar, select the **Legacy** tab, and copy your API keys using the copy button.

![Copy your API keys](/assets/img/fresco-images/uploadthing6.png)

8. Paste your API keys into a text file or notes app for safekeeping. They should look something like this:

```bash
UPLOADTHING_SECRET=sk_live_b9779c445ddaffc45ca4f9c27fd5c9b171d4bc8f6b589c808be29d3262021223
UPLOADTHING_APP_ID=dvrldijrm2
```
``

## Create a database

Expand All @@ -128,8 +88,7 @@ Fresco uses a PostgreSQL database to store data about your study, participants,
6. Paste the environment variables on a new line into the same place you pasted the UploadThing variables for safekeeping. The file should now look something like this:

```bash
UPLOADTHING_SECRET=sk_live_b9779c445ddaffc45ca4f9c27fd5c9b171d4bc8f6b589c808be29d3262021223
UPLOADTHING_APP_ID=dvrldijrm2

POSTGRES_URL="postgres://default:XZ8giBJSQ9tl@ep-snowy-flower-a4ylimlb-pooler.us-east-1.aws.neon.tech:5432/verceldb?sslmode=require"
POSTGRES_PRISMA_URL="postgres://default:XZ8giBJSQ9tl@ep-snowy-flower-a4ylimlb-pooler.us-east-1.aws.neon.tech:5432/verceldb?sslmode=require&pgbouncer=true&connect_timeout=15"
POSTGRES_URL_NO_SSL="postgres://default:XZ8giBJSQ9tl@ep-snowy-flower-a4ylimlb-pooler.us-east-1.aws.neon.tech:5432/verceldb"
Expand Down Expand Up @@ -162,20 +121,6 @@ Should you run into any issues, please consult the [troubleshooting](/en/fresco/

![When you paste your variables, they will be added automatically](/assets/img/fresco-images/vercel-paste-env.png)

<TipBox>

We use anonymous analytics to gather error data from instances of Fresco to troubleshoot issues. No identifiable information of any kind is collected or sent to us.

If you would like to disable all analytics, add an additional environment variable to your Vercel deployment called `DISABLE_ANALYTICS` and set it to `true`. For example:

```bash
DISABLE_ANALYTICS=true
```

By leaving `DISABLE_ANALYTICS` set to `false` (the default) you will help us identify bugs and improve the app.

</TipBox>

5. Click the **"Deploy"** button, and wait for the deployment to finish. Vercel is now building your Fresco instance! This will take 2-5 minutes.

6. Click **"Continue to Dashboard"**, and then click on one of the domain names or the **"Visit"** button.
Expand Down Expand Up @@ -214,6 +159,53 @@ If you forget your password, you **will not be able to reset it**. We recommend

</TipBox>

### Create a storage bucket using UploadThing

Fresco uses a third-party service called 'UploadThing' to store media files, including protocol assets. In order to use this service, you need to create an account with UploadThing that will allow you to generate an API key that Fresco can use to securely communicate with it.

<Tipbox>

Your UploadThing account is unique to you, meaning that no one else will have access to the files stored in your instance of Fresco. For more information about UploadThing, please review the <a href="https://docs.uploadthing.com" target="_blank">UploadThing Docs</a>.

</Tipbox>

To create an app on UploadThing:

1. Go to <a href="https://uploadthing.com" target="_blank">uploadthing.com</a>.

2. Click **"Get started"**.

![Select "Get Started"](/assets/img/fresco-images/uploadthing1.png)

3. Sign in with Github.

4. Authorize UploadThing by clicking **"Authorize pingdotgg"**.

5. You will be prompted to navigate to your dashboard. From the dashboard Click **"Create a new app"**.

![Create a new app](/assets/img/fresco-images/uploadthing4.png)

6. Give your app a name and click **"Create App"**. Do not change the region.

![Create app](/assets/img/fresco-images/uploadthing5.png)

7. From your dashboard, navigate to the **"API Keys"** section from the sidebar and copy your environment variable using the copy button.

![Copy your API keys](/assets/img/fresco-images/uploadthing6.png)

8. Paste your environment variable into the UPLOADTHING_TOKEN field on the form. It should look something like this:

```bash
UPLOADTHING_TOKEN='abCdefGHiJkLmNopQrsTuvWxYz.......'
```

### Set Deployment Settings

Use the toggles to configure the deployment settings for your Fresco instance:

- **Sandbox Mode**: This setting is disabled by default. When enabled, the app will be in a sandbox mode, which disables resetting the database and other features. This is not recommended for most users.
- **Disable Analytics**: Analytics are used to gather error data from instances of Fresco to troubleshoot issues. No identifiable information of any kind is collected or sent to us. If you would like to disable all analytics, enable this setting.

### Upload a protocol

You can optionally upload a protocol. Protocols can also be uploaded from the protocols page once the setup steps are completed.
Expand Down
14 changes: 14 additions & 0 deletions apps/documentation/docs/fresco/deployment/upgrading.en.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,3 +37,17 @@ This version information is accessible from several places:
- **Settings**: You can find the version number and SHA of your Fresco instance on the **Settings** page of your dashboard.
- **GitHub**: You can find the SHA of your Fresco instance on your GitHub repository.
- **Exported Data**: The version number and SHA of your Fresco instance are included in the exported data within the ego file. This information is useful for tracking the version of Fresco used to collect data.

## UploadThing Variable Update

If you are upgrading from a version of Fresco prior to XYZ, you will need to update your UploadThing environment variable after the upgrade process is complete. To do this:

1. Visit your UploadThing dashboard.
2. Navigate to the **API Keys** section from the sidebar and copy your environment variable using the copy button. It should look something like this:

```bash
UPLOADTHING_TOKEN='abCdefGHiJkLmNopQrsTuvWxYz.......'
```

3. Visit your Fresco dashboard. A message will appear informing you that your UploadThing environment variable is out of date.
4. Paste your new environment variable into the **UPLOADTHING_TOKEN** field on the form.

0 comments on commit 186991a

Please sign in to comment.