Merge pull request #69 from jhelvy/pingfan-ui-design

Update deployment.Rmd

vignettes/deployment.Rmd

@@ -17,4 +17,144 @@ knitr::opts_chunk$set(
 )
 ```
 
-This is the page for deployment.
+# Introduction
+
+Great! Now you are ready for online deployment. The purpose of the deployment is to have your survey available online so that you can distribute to your desired audiences and collect their responses efficiently.
+
+In order to deploy your survey, you'll need to have the following recipes ready:
+
+1.  Your survey project made by Quarto that is properly rendered locally.
+2.  Your supabase project with its credentials defined in your survey `.qmd` file. See [5. Database Setup](../doc/database_setup.html) for details.
+3.  An account on [shinyapps](https://www.shinyapps.io), which will be used for survey online deployment.
+
+These steps are easy to follow. We will go through one by one.
+
+# Demo Survey
+
+If you have trouble constructing your own survey, we have prepared a demo survey:
+
+1.  [Online demo survey](https://pingfan.shinyapps.io/demo/)
+2.  [GitHub repository](https://github.com/jhelvy/surveydown_demo)
+
+This survey was made on [RStudio](https://posit.co/products/open-source/rstudio/) using the {surveydown} R package and the surveydown Quarto extension, with survey data stored on [supabase](https://supabase.com), and its online website deployed on [shinyapps](https://www.shinyapps.io).
+
+# Step 1: Survey Project
+
+## Step 1-1: Construct your survey
+
+Pick an IDE that is compatible with R and Quarto ([RStudio](https://posit.co/products/open-source/rstudio/), [VS Code](https://code.visualstudio.com), [Cursor](https://www.cursor.com), etc.), and construct your survey using the {surveydown} R package and the surveydown Quarto extension.
+
+The previous articles in **Usage Guide** are sufficient to guide you through the survey construction process.
+
+## Step 1-2: Password as environment variable
+
+One important setting is the **password** of your supabase project. Here's how.
+
+Firstly, while you set up your supabase project, you will create a password for it. This password can be saved as an *environment variable* in your survey project, which we'll cover soon.
+
+Secondly, in the very end of your survey `.qmd` file, you'll need to define the `db` variable, which should be the settings of your [supabase](https://supabase.com) project. There is an argument called `password`. You can directly paste your password here as `password = "your_password"`, but it's not recommended since this will make your supabase project unsafe.
+
+We recommend you to use `password = Sys.getenv("SUPABASE_PASSWORD")` and define the `SUPABASE_PASSWORD` in `.Renviron`, which is the file that stores environment variables. Please define your password like this:
+
+```{r eval=FALSE}
+db <- sd_database(
+  # Other settings...
+  password = Sys.getenv("SUPABASE_PASSWORD")
+)
+```
+
+> The instructions below teach you to construct/edit **two** `.Renviron` files for local rendering and online deployment. Since the online deployment relies on the local rendering, you need to complete **both** of the `.Renviron` files.
+
+Now, here is the critical thing. In order to make this `password = Sys.getenv("SUPABASE_PASSWORD")` work **locally**, you need to run `usethis::edit_r_environ()` in your **R Console**. It will summon the system `.Renviron` file. In this file, you can define:
+
+```{r eval=FALSE}
+SUPABASE_PASSWORD=your_password
+```
+
+Note that there is NO quotation mark needed for your password.
+
+In order to make this `password = Sys.getenv("SUPABASE_PASSWORD")` work **online**, you need to create an `.Renviron` file in your survey project root folder, and paste the same contents in it:
+
+```{r eval=FALSE}
+SUPABASE_PASSWORD=your_password
+```
+
+After that, make sure you have `.Renviron` included in your `.gitignore` file, so that it won't be pushed to your GitHub repo and will only be saved locally. The `.Renviron` file is usually hidden, which further increases its safety.
+
+## Step 1-3: Render your `.qmd` file
+
+This is simple: just hit **Render** or `cmd`/`ctrl` + `shift` + `K` (Mac/Win). But the reason why I make this a stand-alone step is that, WITHOUT rendering your `.qmd` file, your survey CANNOT be deployed online.
+
+One more thing... If you fail to deploy locally while you have set every argument correctly in your `db` variable, try to define `gssencmode = "disable"` in your `db` variable:
+
+```{r eval=FALSE}
+db <- sd_database(
+  # Other settings...
+  gssencmode = "disable"
+)
+```
+
+This can help solve your connection problem. The value of `gssencmode` is set to `"prefer"` by default.
+
+# Step 2: Supabase Project
+
+This is covered in [5. Database Setup](../doc/database_setup.html). I want to further mention that you don't need to actively create any table on your supabase project. In your `db` variable of your `.qmd` file, there is a `table_name` argument. Whatever name you define here will become the table name of your supabase:
+
+```{r eval=FALSE}
+db <- sd_database(
+  # Other settings...
+  table_name = "demo"
+)
+```
+
+In the above example, the table name in my supabase project will be `"demo"`. If your survey project runs successfully locally and can have survey data collected in supabase, you are ready for your online deployment.
+
+# Step 3: Online Deployment
+
+So this is our final step: to deploy your survey online. I'm glad you've made this far! You are almost there!
+
+We'll use [shinyapps.io](https://www.shinyapps.io). Now before we start, here are two explanations to clear out your possible questions:
+
+1.  [shinyapps.io](https://www.shinyapps.io) can support both [Shiny Apps](https://shiny.posit.co/r/getstarted/shiny-basics/lesson1/index.html) and [Quarto Shiny Documents](https://quarto.org/docs/dashboards/interactivity/shiny-r.html). In our case, our survey is considered as a Quarto Shiny Document.
+2.  [Quarto Pub](https://quartopub.com) is also a website publishing platform. In fact, both Quarto Pub and shinyapps.io are provided by [Posit](https://posit.co). However, we DON'T use Quarto Pub for our survey deployment. The core reason is that, shinyapps.io can make interactive websites, but Quarto Pub only makes static websites. A survey is apparently an interactive website, so it's compatible with shinyapps.io, not Quarto Pub.
+
+To start using shinyapps.io, you'll need to create an account and follow the basic instructions to set up your sub-domain and authorize your IDE. See more information [here](https://docs.posit.co/shinyapps.io/guide/getting_started/).
+
+Once you have your account and your sub-domain ready, it's time to deploy your survey website.
+
+Make sure you have the [rsconnect](https://rstudio.github.io/rsconnect/) R package installed (You should have done this while you authorize your IDE):
+
+```{r eval=FALSE}
+install.packages('rsconnect')
+```
+
+The simplest way is to run this:
+
+```{r eval=FALSE}
+rsconnect::deployDoc("your_survey.qmd")
+```
+
+The URL of this page will be your domain followed by `/your_survey`, which means the name of your `.qmd` file will be in the URL. The tab name of the HTML page is also `your_survey`. Better give a good name to your `.qmd` file.
+
+**Again, you'll need to firstly render locally and make sure it works properly. Otherwise, this deployment will fail.**
+
+If you want to define a different tab name for your survey page, run:
+
+```{r eval=FALSE}
+rsconnect::deployDoc(
+  doc = "your_survey.qmd",
+  appName = "Survey Name"
+)
+```
+
+Now you should have your survey site deployed. The survey is now served on **shinyapps.io**, with its data stored on **supabase**. Congratulations!
+
+Further explanation (with my personal interpretation) of the deployment functions:
+
+In rsconnect, there are two functions that can be used for deployment: `deployApp()` and `deployDoc()`. They serve different purposes and should NOT be mix-used.
+
+1.  `deployApp()` is used to deploy a Shiny App. It doesn't work for `.qmd`, but works for Shiny App and `.rmd`, and it accepts multiple files.
+2.  `deployDoc()` is used to deploy a Quarto Shiny Document. It works for a single file and tries to "automatically discover dependencies" (direct paste from [official instructions](https://rstudio.github.io/rsconnect/reference/deployDoc.html)).
+3.  Since our survey is a Quarto Shiny Document, we use `deployDoc()`.
+
+> I guess `deployDoc()` is a newer function that specifically works for `.qmd`. I have a feeling that this function is specifically made for `.qmd` to match the fact of "single document" and "dependencies". In our case, `deployDoc()` is a perfect match.