Skip to content

Commit

Permalink
update docs, add new imgs
Browse files Browse the repository at this point in the history
  • Loading branch information
buckhalt committed Oct 17, 2024
1 parent 186991a commit 8b4f3b9
Show file tree
Hide file tree
Showing 11 changed files with 17 additions and 103 deletions.
95 changes: 1 addition & 94 deletions apps/documentation/docs/fresco/deployment/advanced.en.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -48,87 +48,13 @@ Fresco is configured using environment variables. These variables specify how to
Create an `.env` file somewhere on your host machine using the template below. The next steps will guide you through setting up the environment variables and adding them to this file.

```bash
# -------------------
# Optional environment variables
# -------------------

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

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

POSTGRES_PRISMA_URL=
POSTGRES_URL_NON_POOLING=

PUBLIC_URL=

```

<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, set `DISABLE_ANALYTICS` to `true`.

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

</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"**. Performance can be improved by selecting a region close to your server, although this will require a paid plan.

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

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

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

8. Pate your API keys into the `.env` file you created in the previous step:

```bash
# -------------------
# Optional environment variables
# -------------------

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

# -------------------
# Required environment variables
# -------------------
UPLOADTHING_SECRET=sk-your-secret-key
UPLOADTHING_APP_ID=your-app-id

POSTGRES_PRISMA_URL=
POSTGRES_URL_NON_POOLING=

PUBLIC_URL=
```

Expand All @@ -150,13 +76,6 @@ If your database is hosted on a service such as PlanetScale or Neon, use the con
Add your connection strings to the `.env` file:

```bash
# -------------------
# Optional environment variables
# -------------------

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

# -------------------
# Required environment variables
# -------------------
Expand All @@ -178,19 +97,9 @@ If you intend to run your instance on a LAN or private network, **at least the `
Add your URL to the `.env` file:

```bash
# -------------------
# Optional environment variables
# -------------------

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

# -------------------
# Required environment variables
# -------------------
UPLOADTHING_SECRET=sk-your-secret-key
UPLOADTHING_APP_ID=your-app-id

POSTGRES_PRISMA_URL=postgresql://username:password@hostname:port/dbname
POSTGRES_URL_NON_POOLING=postgresql://username:password@hostname:port/dbname

Expand Down Expand Up @@ -220,8 +129,6 @@ You can optionally use [Docker Compose](https://docs.docker.com/compose/) to man
services:
fresco:
environment:
- UPLOADTHING_SECRET=sk-your-secret-key
- UPLOADTHING_APP_ID=your-app-id
- POSTGRES_PRISMA_URL=postgresql://username:password@postgres:5432/fresco
- POSTGRES_URL_NON_POOLING=postgresql://username:password@postgres:5432/fresco
- PUBLIC_URL=https://your-public-url.com
Expand Down Expand Up @@ -269,7 +176,7 @@ docker-compose up -d -f docker-compose.yml

## Access Fresco

You can now access Fresco by visiting the `PUBLIC_URL` that you have configured. You should be greeted with the onboarding wizard, which will guide you through the process of setting up Fresco.
You can now access Fresco by visiting the `PUBLIC_URL` that you have configured. You should be greeted with the onboarding wizard, which will guide you through the process of setting up Fresco. This will include configuring UploadThing.

For details on this process, refer to the [configuration and setup](./guide#configuration-and-setup) section of the basic deployment guide.

Expand Down
21 changes: 13 additions & 8 deletions apps/documentation/docs/fresco/deployment/guide.en.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ date: 17th April 2024
navOrder: 1
---

<SummaryCard duration="20 minutes">
<SummaryCard duration="60 minutes">

<SummarySection>
This guide will walk you through the process of deploying your instance of Fresco.
Expand Down Expand Up @@ -137,7 +137,7 @@ To use Fresco, you need to set up an administrator account which will enable you

<TipBox danger>

To ensure the security of your deployment, you have **30 minutes** from when the app is deployed to create a user account. If this time elapses without a user account being created, your configuration will expire. To redeploy, follow our guide to [reset your database](/en/fresco/deployment/troubleshooting#instance-expired-message-during-the-setup-process).
To ensure the security of your deployment, you have **2 hours** from when the app is deployed to complete the configuration and setup. If this time elapses before completing all setup steps, your configuration will expire. To redeploy, follow our guide to [reset your database](/en/fresco/deployment/troubleshooting#instance-expired-message-during-the-setup-process).

</TipBox>

Expand Down Expand Up @@ -199,26 +199,31 @@ To create an app on UploadThing:
UPLOADTHING_TOKEN='abCdefGHiJkLmNopQrsTuvWxYz.......'
```

### Set Deployment Settings
![Paste your environment variable into the form](/assets/img/fresco-images/uploadthing7.png)

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

- **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.
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, toggle the **"Disable Analytics"** setting to **true**.

Leaving Disable Analytics set to **false** (the default) will help us identify bugs and improve the app.

![Optionally disable analytics](/assets/img/fresco-images/fresco2.png)

### 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](/assets/img/fresco-images/fresco2.png)
![Upload a protocol](/assets/img/fresco-images/fresco3.png)

### 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](/en/fresco/using-fresco) guide.

![Import participants and optionally allow anonymous recruitment](/assets/img/fresco-images/fresco3.png)
![Import participants and optionally allow anonymous recruitment](/assets/img/fresco-images/fresco4.png)

### Visit the dashboard

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ You may be redirected to a page that informs you that your instance has expired.

</summary>

When completing the initial setup for Fresco, you have 30 minutes to complete the process. If you exceed this time, you will be redirected to a page that informs you that your instance has expired. If this happens, you must delete your database and create a new one.
When completing the initial setup for Fresco, you have 2 hours to complete the process. If you exceed this time, you will be redirected to a page that informs you that your instance has expired. If this happens, you must delete your database and create a new one.

To delete your database:

Expand Down
2 changes: 2 additions & 0 deletions apps/documentation/docs/fresco/deployment/upgrading.en.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -51,3 +51,5 @@ If you are upgrading from a version of Fresco prior to XYZ, you will need to upd

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.

![Paste your new environment variable into the form](/assets/img/fresco-images/upgrade.png)
Binary file modified apps/documentation/public/assets/img/fresco-images/fresco1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified apps/documentation/public/assets/img/fresco-images/fresco2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified apps/documentation/public/assets/img/fresco-images/fresco3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit 8b4f3b9

Please sign in to comment.