fresco 🠖 deployment

Deployment Guide 

Summary:

This guide will walk you through the process of deploying your instance of Fresco, including forking the repository, setting up database infrastructure, and deploying to the web.

Prerequisites:

Before you get started, you should:
  • Read the about Fresco article to understand what Fresco is and how it works.
  • Create an account on GitHub if you do not already have one.
  • Set aside enough time to complete the deployment process in one sitting. The process could take up to an hour, particularly if you are unfamiliar with the technology or the process.

Duration:

60 minutes

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, including forking the repository, setting up database infrastructure, and deploying to the web.

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, or prefer the peace of mind associated with guaranteed levels of performance, you may wish to use a paid-for cloud provider/database service if your project requires additional features, performance, or capacity. 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.

Required services

Fresco is different from other software that you may have installed previously. It is a "self-hosted" web application, meaning that you do not install it on a laptop or desktop. Instead, you "deploy" it to one or more servers on the Internet (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.

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

To make the deployment process as simple as possible, we designed Fresco to be easily deployed on the Vercel platform, which provides both the Node.js and the PostgreSQL services for you (for free).

Vercel 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, but it is the simplest way to get started, and is the method we will be using in this guide.

Initial Deployment to Vercel

Deploying Fresco to Vercel involves setting up your own unique version of the project, which we refer to as your instance. This instance will be hosted on Vercel's servers and will be accessible via a unique URL. You will be able to access your instance of Fresco from any web browser by visiting this URL.

Before continuing, ensure you have created a GitHub account and are signed in. To create a GitHub account, visit github.com.

Step 1: Create an app on UploadThing

Fresco uses a third-party service called UploadThing to store media files, including protocol assets. The first step in deploying Fresco is to create an account with UploadThing that will allow us to generate an API key that Fresco will use to communicate with the service.

To create an app on UploadThing:

  1. Go to uploadthing.com.

  2. Click "Get started".

    Select "Get Started"
    Select "Get Started"
  3. Sign in with Github.

    Sign In with GitHub
    Sign In with GitHub
  4. Authorize UploadThing by clicking "Authorize pingdotgg".

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

    Create a new app
    Create a new app
  6. Give your app a name and click "Create App".

    Create app
    Create app
  7. From your dashboard, navigate to the "API Keys" section from the sidebar and copy your API keys.

    Copy your API keys
    Copy your API keys

For more information about UploadThing, please review the UploadThing Docs.

Step 2: Fork Fresco Repository

The next step requires us to create a copy (or "fork") of the Fresco code. This will allow us to deploy our own unique instance of Fresco.

To create a fork of the Fresco repository:

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

  2. Create your Fork

    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), description (optional), and click "Create Fork".

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 as you wish.

Step 3: Deploy your fork to Vercel

Next, we will deploy your fork to the Vercel platform. 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.

  2. Import Git Repository

    Find your Fresco instance from the list of your git repositories and click "Import".

    Import Git Repository
    Import Git Repository

  3. Configure Environment Variables

    Configure Environment Variables and Deploy
    Configure Environment Variables and Deploy

    Copy the template below and paste it into the Environment Variables section in Vercel to pre-populate the form with the required environment variables.

    Replace the values with your environment variable values from UploadThing you copied in Step 1

    UPLOADTHING_SECRET=your_uploadthing_api_key
    UPLOADTHING_APP_ID=your_uploadthing_app_id
    
  4. Deploy

    Click "Deploy" and wait for the deployment to finish.

  5. Go to Project

    After the initial deployment fails, select "Go to Project" to view your project dashboard.

    Initial Deployment Failed. Click Go to Project.
    Initial Deployment Failed. Click Go to Project.

Step 4: Create your database

  1. From your project dashboard, select "Storage". Then, select Create within the Postgres row.

    Storage
    Storage
    Create a Postgres database
    Create a Postgres database

  2. Review and accept the terms in the modal.

    Accept terms
    Accept terms

  3. Give your database a name and select the region that is closest to where you and your participants will be located. Then, click "Create". Your database will be generated and you will be redirected to the Getting Started page.

    Enter a name and create the database
    Enter a name and create the database
  4. You will be prompted to connect your project. Select "Connect".

    Connect database to your project
    Connect database to your project
  5. Select the "Deployments" tab. Click on the menu beside the most recent deployment and select "Redeploy". This will redeploy your project with your new connected database.

    Redeploy app
    Redeploy app

Step 5: Visit your deployed app

Visit your deployed Fresco app by clicking on the preview or go to your dashboard by clicking "Continue to Dashboard".

Continue to dashboard
Continue to dashboard

Then, click on one of the domain names or the "Visit" button.

Visit domain
Visit domain

Step 6 (Optional): Set up a custom domain

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.

    Navigate to domains section
    Navigate to domains section
  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.
    Domain setup options
    Domain setup options

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 an account

Visit your deployed app and enter a username and password.

Enter a username and password
Enter a username and password

Upload a protocol

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

Upload a protocol
Upload a protocol

Configure participation

Visit the Dashboard

Click the "Go to the dashboard" button and begin your exciting exploration of Fresco.