Deployment Guide 

Thank you for taking the time to deploy Fresco! We hope you find it a valuable tool for your research and data collection. This guide will walk you through the process of deploying your instance of Fresco.

Fresco is different from other software that you may have installed previously. It is a web application, meaning that you do not install it on a laptop or desktop. Instead, you "deploy" it to one or more servers (your "infrastructure"), which you can then access from your web browser.

This approach allows researchers to manage their own data and customize the nature of their infrastructure to suit their needs.

This also means that you are responsible for the security and maintenance of your own deployment! The Network Canvas project team by design has no access to your data or infrastructure.

To deploy Fresco, we will use the following services and technologies:

• GitHub: A platform for hosting and sharing code owned and operated by Microsoft. The Fresco code is shared via GitHub, and you will need a GitHub account to deploy it. If you do not have a GitHub account, you can create one for free at github.com.
• PostgreSQL: A powerful, open-source relational database system. Fresco uses PostgreSQL to store data about your study, participants, and responses.
• UploadThing: A cloud-based file storage service that Fresco uses to store protocol assets such as media files.

To make the deployment process as simple as possible, we designed Fresco to be deployed using Vercel, which is a cloud platform that specializes in deploying web applications. It is designed to be easy to use and has a generous free tier that is suitable for most research projects. It is not a requirement to use Vercel to host Fresco, but it is the simplest way to get started and is the method we will be using in this guide.

How much does deploying Fresco cost?

Deploying Fresco for your study can be achieved entirely for free using the steps detailed in this guide. We built it this way to allow the broadest possible access to the software. The free deployment method does come with some limitations, such as the amount of data you can store and transfer, and the overall performance of the application.

If you are running a large study, require guaranteed levels of performance, or have special requirements imposed by your IRB regarding participant data, you may wish to use a paid plan or a different approach to deployment. Consult the cloud pricing page for more information. Please note that the Network Canvas team does not benefit financially in any way from your choice of cloud provider.

It is also possible to use whatever infrastructure you may have access to in order to deploy Fresco. For information on this, see our advanced deployment guide.

Create a fork of Fresco

Deploying Fresco involves setting up your own unique version of the project, which we refer to as your instance. The first step in creating this instance is to create a copy (or "fork") of the Fresco code on GitHub.

To do this, ensure you have a GitHub account and are signed in, and then:

1. Visit the Fresco repository on GitHub, and click "Fork".

   

2. Enter a repository name (this will be your Fresco instance name, so you may wish to use your study name or the name of your project), along with a description, and click "Create Fork". Leave the "copy main branch" option selected.

   

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 database

Fresco uses a PostgreSQL database to store data about your study, participants, and responses. We will next create a new database using the Vercel platform.

1. Visit the Vercel website and click Continue with GitHub to sign in. You will be redirected to the Vercel dashboard.

2. From your dashboard, select "Storage" from the top navigation bar. Then, click Create next to Postgres ('Serverless SQL').

   

3. Review and accept the terms in the modal.

   

4. Give your database a name, and then click "Create". Do not change the region. Your database will be generated and you will be redirected to the Getting Started page.

   

5. Under the heading 'quickstart' you will see a connection string for the database. Click the .env.local tab, and then click "Copy Snippet" to copy the environment variables to your clipboard.

   

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:

   
   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"
   POSTGRES_URL_NON_POOLING="postgres://default:XZ8giBJSQ9tl@ep-snowy-flower-a4ylimlb.us-east-1.aws.neon.tech:5432/verceldb?sslmode=require"
   POSTGRES_USER="default"
   POSTGRES_HOST="ep-snowy-flower-a4ylimlb-pooler.us-east-1.aws.neon.tech"
   POSTGRES_PASSWORD="XZ8giBJSQ9tl"
   POSTGRES_DATABASE="verceldb"
   

Create a project on Vercel

Next, we will deploy your fork to the Vercel platform, using the services we created previously. You can use the "hobby" tier (which is free) or paid plan (for more information about cloud pricing, read our cloud pricing documentation), but for the purposes of this guide, we will use the free tier.

1. Click here to create a new project on Vercel. Sign in using GitHub, if you are not already signed in.

2. Find the name of your Fresco instance from the list of your git repositories and click "Import". You will be taken to the "Configure Project" screen.

   

3. Open the text editor or notes app where you stored your environment variables from UploadThing and the database. Select all of the text, and copy it to your clipboard.

4. On the "Configure Project" screen, expand the "Environment Variables" section. Paste your variables into the "key" text box (with the EXAMPLE_NAME placeholder). Your variables will be automatically added below.

   

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.

   

Then, click on the "Visit" button or the domain.

Configuration and setup

To use Fresco, you need to set up an administrator account which will enable you to access the protected parts of the app for study management. Only one administrator account can be created.

Create a user account

Visit your deployed app and create an account by entering a username and password. Ensure you make the password as strong as possible!

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.

To create an app on UploadThing:

1. Go to uploadthing.com.

2. Click "Get started".

   

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".

   

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

   

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

   

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

   UPLOADTHING_TOKEN='abCdefGHiJkLmNopQrsTuvWxYz.......'
   

   

Upload a protocol

You can optionally upload a protocol. Protocols can also be uploaded from the protocols page once the setup steps are completed.

Configure participation

• Import participants: You can optionally upload a CSV file containing participants you wish to recruit to your study. Participants can also be uploaded from the participants page once the setup steps are completed.

• Allow anonymous recruitment: You can enable this setting to allow your participants to join your study by visiting a URL. More information about anonymous recruitment can be found in the using Fresco guide.

Visit the dashboard

Click the "Go to the dashboard" button and to begin using Fresco!

Set up a custom domain (optional)

If you prefer to use a custom domain for your Fresco instance, you can configure this in the Vercel dashboard by following these steps:

1. Navigate to your project dashboard. Here, locate and click on the "Domains" button.

   

2. In the Domains section, you have two options:

   • If you have a purchased domain, you can add it here.
   • Alternatively, you can modify the default Vercel domain to suit your needs.