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.
• Object storage: Fresco stores protocol assets (such as media files) in an S3-compatible object store. You can use UploadThing — a managed service that is the simplest option — or bring your own S3-compatible bucket (AWS S3, Cloudflare R2, MinIO, or Backblaze B2).

To make the deployment process as simple as possible, we designed Fresco to be deployed using Netlify, 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 Netlify to host Fresco, but it is the simplest way to get started and is the method we will be using in this guide.

We previously suggested deploying to Fresco to another cloud platform, Vercel, which offers many of the same features as Netlify. The Vercel deployment guide is still available, should you wish to use it.

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 Neon platform.

1. Visit the Neon website and click Login. We recommend connecting to Neon with GitHub by clicking the GitHub button. You will be redirected to the Neon dashboard.

2. From your dashboard, select Create Project.

   

3. Give your database a name and optionally choose a region from the dropdown. By default, the database will be created on the Free tier. For more information on database tier pricing, consult the cloud pricing page. Then, click Create. Your database will be generated and you will be redirected to the Project dashboard.

1. Under the heading 'Connect to your databse' click Connect.

   

2. Choose Prisma from the dropdown and select the .env tab. You will see environment variables for your database. Click "Copy Snippet" to copy the environment variables to your clipboard.

   

3. Paste the environment variables into a text file or notes app for safekeeping. You will need these environment variables later in the deployment process.

DATABASE_URL="postgresql://neondb_owner:***************@ep-wispy-thunder-aduy7cf8-pooler.c-2.us-east-1.aws.neon.tech/neondb?sslmode=require&channel_binding=require"
# uncomment next line if you use Prisma <5.10
DATABASE_URL_UNPOOLED="postgresql://neondb_owner:*************@ep-wispy-thunder-aduy7cf8.c-2.us-east-1.aws.neon.tech/neondb?sslmode=require&channel_binding=require"

Create a project on Netlify

Next, we will deploy your fork of the application to the Netlify platform. You can use the Free tier or paid plans (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 Netlify. Sign in using GitHub, if you are not already signed in.

2. Under the Let's deploy your project with... header, select GitHub.

   

3. Authorize GitHub permissions. You will be redirected back to the Netlify project creation dashboard.

4. Find the name of your Fresco instance from the list of your git repositories and click on it.

5. Give your project a name. The project name determines the default URL for your project. If none is provided, a random project name will be generated for you.

   

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

7. Scroll to the bottom of the screen. Click "Add environment variables". Then, click Import from a .env file.

   

8. Paste your variables into the "Contents of .env file" text box (with the EXAMPLE_KEY_1=my-secret-value-1 placeholder). Your variables will be automatically added. Then, check the box beside Contains secret values.

   

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

10. Once your app is deployed, click on the deployment URL. It will be listen in green under your project name once it is deployed.

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. This is the first account for your instance; you can add further accounts later from the dashboard.

Create a user account

Visit your deployed app and create your first account. You can secure it with a username and password (make the password as strong as possible), or with a passkey instead. In Fresco v4 and later you can add more accounts, enable two-factor authentication, and register passkeys later from the dashboard. See Accounts & security.

Configure storage

Fresco stores protocol assets — such as images, audio, video, and network files — in an S3-compatible object store. You can use one of two storage providers:

• UploadThing — a managed storage service. This is the simplest option and what we recommend for most studies: you create an account, generate a token, and paste it in.
• An S3-compatible bucket — AWS S3, Cloudflare R2, MinIO, Backblaze B2, or any S3-compatible endpoint. Consider this if you need control over the storage region and data residency, want to keep all components within your own infrastructure, or already have S3 storage available.

Create a storage bucket using UploadThing

Fresco can use a third-party service called 'UploadThing' to store media files, including protocol assets. To use this service, you create an account with UploadThing that lets you generate an API token that Fresco uses 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.......'
   

   

Use an S3-compatible bucket

If you would rather use your own storage, select S3 / S3-Compatible on the storage step instead of UploadThing.

Before you start, create a bucket with your S3 provider (AWS S3, Cloudflare R2, MinIO, Backblaze B2, etc.), generate an access key and secret with read and write access to it, and set the bucket's CORS policy to allow requests from your Fresco domain.

Then complete the form:

1. Endpoint URL — your provider's S3 endpoint (for example https://s3.amazonaws.com).
2. Public URL — the URL browsers use to reach the storage. For AWS S3 or Cloudflare R2 this is usually the same as the endpoint URL.
3. Bucket Name, Region, Access Key ID, and Secret Access Key for your bucket.

Click Save and continue. Fresco verifies the connection before moving on.

Upload a protocol

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

Finish setup

The final step of the wizard confirms that your instance is ready and links to documentation. Click Go to the dashboard! to begin using Fresco.

Everything else is managed from the dashboard. In particular, add participants from the Participants page — individually or by importing a CSV — and enable anonymous recruitment, which lets participants join your study by visiting a URL, from Settings. See the Using Fresco guide for both.

Set up a custom domain (optional)

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

1. Navigate to your project dashboard. Click on the Domain Management tab.

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

   • If you have a purchased domain, you can add it here by clicking Add a domain.
   • Alternatively, you can modify the default Netlify domain to suit your needs by clicking Options and then Edit project name.