diff --git a/README.md b/README.md index e7d5fd0..1b52acf 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@

Quice

- Self-hosted form submission service + The Self-Hosted Form Submission Service

@@ -16,19 +16,26 @@

- Features + Features • - Demo + Demo • - Get Started + Get Started • - Contribute + Contribute

--- -Lorem ipsum dolor, sit amet consectetur adipisicing elit. Enim nam nihil nostrum -qui at totam amet vel soluta necessitatibus. Corporis. +Quice is a headless service to handle any kind of form submissions. It is meant +to be self-hosted on Vercel and uses Firebase for backend services. It exposes a +REST endpoint to which you can send arbitrary JSON to, which will then be stored +in Cloud Firestore. + +All submissions can be accessed through the web interface, where the submission +data will be displayed in an organized layout. + +![Web interface of Quice](./assets/screenshot.png)
@@ -87,9 +94,110 @@ refuse to create your own account. ## ❯ Get Started -Lorem ipsum dolor sit amet consectetur, adipisicing elit. Corporis fugiat alias -blanditiis eveniet impedit fugit voluptatem quis explicabo expedita velit -asperiores itaque deleniti. +In this paragraph you will deploy your own instance of Quice with the Firebase +console and the Vercel deploy button. + +### 1. Create a new firebase project + +Head to [console.firebase.google.com](https://console.firebase.google.com/) and +log in. Then hit the create a new project button and give it a name: + +![The firebase project creation screen](./assets/setup/project-creation.png) + +Disable Google Analytics for the project and then create it. You will now be +redirected into the Firebase Console. Now we have to enable the different +features Quice is going to use, first off Firebase Authentication. + +Head over to the authentication tab in the menu and click the Get Started +button. Enable the "Email/Password" provider and hit save. + +![The authentication provider page of the Firebase console](./assets/setup/enable-auth.png) + +That's it for authentication, now we want to enable Firestore. Go over to the +"Cloud Firestore" tab in the menu, which is right below Authentication. + +Click on "Create Database", choose the Production mode for security rules and +choose any region that is closest to you. + +> Your Vercel deployment will be in US east, which cannot be changed for free +> accounts, so you cannot go wrong with picking `us-central` as the location, +> since it is the closest to your Vercel deployment. Read more about Vercel +> regions [here](https://vercel.com/docs/edge-network/regions). + +We will now set up the Firestore security rules, which you can find under the +"Rules" tab along the top tab bar. Here you want to paste the content of the +most recent security rules file for Quice, which can be found +[here](https://github.com/leodr/quice/blob/main/firebase/firestore.rules). + +After that we have to create two composite indexes. Head over to the "Indexes" +settings in the top tab bar and create an index. + +The first index will go on the `submissions` collection and index the fields +`done` ascending and `createdAt` descending. Set "Collection" as the query +scope: + +![](./assets/setup/index-1.png) + +The second index will also go on the `submissions` collection, but it will index +the fields `formId` ascending and `createdAt` descending. Set "Collection" as +the query scope: + +![](./assets/setup/index-2.png) + +This is it for setting up Firebase, but don't close the Firebase console quite +yet! + +### 2. Collect Environment Variables + +We will now collect the Firebase credentials which will be supplied to the +deployment as environment variables. Click the deploy button below and create +the project until you get to the project settings where you will be asked to +enter environment variables. + +

+ Deploy with Vercel +

+ +Your page should look something like this: + +![The Vercel setup page for environment variables](./assets/setup/vercel-env-variables.png) + +First we will grab the credentials for a Firebase service account. In the +Firebase console, hit the little cog icon at the top of the sidebar menu, go to +"Project settings" and in the top tab bar choose "Service accounts". + +![The service accounts page of the Firebase console](./assets/setup/firebase-service-account.png) + +Here generate a new private key. You will download a JSON file, from which you +want to grab the `private_key` and `client_email` entries and paste them into +the `FIREBASE_PRIVATE_KEY` and `FIREBASE_CLIENT_EMAIL` fields on the Vercel +deployment form. + +> It is important that these are not prefixed with `NEXT_PUBLIC_` because we do +> not want to expose them to the browser environent. + +Next we will grab the credentials for the web interface. For this go the +"Project overwiew" and hit the white "Web app" button on next to the iOS and +Android buttons. + +Give the app an arbitrary name (e.g. "Web interface") and disable Firebase +hosting. You will then be presented with a short code snippet. Here we are +interested in the `firebaseConfig` object. + +![](./assets/setup/web-app-credentials.png) + +Grab these keys from the config object and paste them into the Vercel deployment +console: + +| `firebaseConfig` key | Vercel environment variable | +| -------------------- | ---------------------------------- | +| `apiKey` | `NEXT_PUBLIC_FIREBASE_API_KEY` | +| `authDomain` | `NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN` | +| `projectId` | `NEXT_PUBLIC_FIREBASE_PROJECT_ID` | +| `appId` | `NEXT_PUBLIC_FIREBASE_APP_ID` | + +After that you can finish up the Vercel deployment and visit your fully set up +site!
diff --git a/assets/github-banner.png b/assets/github-banner.png index f730a9a..49d8b80 100644 Binary files a/assets/github-banner.png and b/assets/github-banner.png differ diff --git a/assets/screenshot.png b/assets/screenshot.png new file mode 100644 index 0000000..9d563f3 Binary files /dev/null and b/assets/screenshot.png differ diff --git a/assets/setup/enable-auth.png b/assets/setup/enable-auth.png new file mode 100644 index 0000000..bfe1037 Binary files /dev/null and b/assets/setup/enable-auth.png differ diff --git a/assets/setup/firebase-service-account.png b/assets/setup/firebase-service-account.png new file mode 100644 index 0000000..7ff8afc Binary files /dev/null and b/assets/setup/firebase-service-account.png differ diff --git a/assets/setup/index-1.png b/assets/setup/index-1.png new file mode 100644 index 0000000..ff3281d Binary files /dev/null and b/assets/setup/index-1.png differ diff --git a/assets/setup/index-2.png b/assets/setup/index-2.png new file mode 100644 index 0000000..15935eb Binary files /dev/null and b/assets/setup/index-2.png differ diff --git a/assets/setup/project-creation.png b/assets/setup/project-creation.png new file mode 100644 index 0000000..835ac16 Binary files /dev/null and b/assets/setup/project-creation.png differ diff --git a/assets/setup/vercel-env-variables.png b/assets/setup/vercel-env-variables.png new file mode 100644 index 0000000..caae998 Binary files /dev/null and b/assets/setup/vercel-env-variables.png differ diff --git a/assets/setup/web-app-credentials.png b/assets/setup/web-app-credentials.png new file mode 100644 index 0000000..621929d Binary files /dev/null and b/assets/setup/web-app-credentials.png differ