Technical docs (#553)

* WIP

* Working on configuration

* wip

* Finished docs

* Self hosted comparison + more links

Author: JhumanJ

README.md

@@ -20,244 +20,37 @@
 <a href="https://console.algora.io/org/OpnForm/bounties?status=completed"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fconsole.algora.io%2Fapi%2Fshields%2FOpnForm%2Fbounties%3Fstatus%3Dcompleted" alt="Rewarded Bounties"></a>
 </p>
 
-> An open-source form builder. It's an alternative to products like Typeform, JotForm, Tally etc.
+OpnForm is an open-source form builder.
 
-## Features
+## Get Started
 
--   No-code form builder, with infinite number of fields & submissions
--   Text inputs, Date inputs, URL inputs, Phone inputs, Email inputs, Checkboxes, Select and Multi-Select inputs, Number Inputs, Star-ratings, File uploads & more
--   Embed anywhere (on your website, in your Notion page, etc)
--   Email notifications (for both form owner & form respondents)
--   Hidden fields
--   Form passwords
--   URL form pre-fill
--   Slack integration
--   Webhooks
--   Form logic
--   Customize colors, add images or even some custom code
--   Captcha form protection
--   Form closing date
--   Limit the number of submissions allowed
+The easiest way to get started with OpnForm is to sign up for our [managed service in the Cloud](https://opnform.com/). You get support, backups, upgrades, and more. Your data is safe and secure, and you don't need to worry about maintenance or infrastructure. Check out our quick overview of [cloud vs self-hosting](https://docs.opnform.com/deployment/cloud-vs-self-hosting).
 
-And much more!
+## Key Features
 
-## Bounties
+-   🚀 No-code builder with unlimited forms & submissions
+-   📝 Various input types: Text, Date, URL, File uploads & much more
+-   🌐 Embed anywhere
+-   📧 Email notifications
+-   💬 Integrations (Slack, Webhooks, Discord)
+-   🧠 Form logic & customization
+-   🛡️ Captcha protection
+-   📊 Form analytics
 
-Get paid for contributing to OpnForm! Here are our open bounties:
+For a complete list of features and detailed documentation, visit our [Technical Documentation](https://docs.opnform.com).
 
-<a href="https://console.algora.io/org/OpnForm/bounties?status=open">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://console.algora.io/api/og/OpnForm/bounties.png?p=0&status=open&theme=dark">
-    <img alt="Bounties of OpnForm" src="https://console.algora.io/api/og/OpnForm/bounties.png?p=0&status=open&theme=light">
-  </picture>
-</a>
-
-## Getting started with OpnForm
-
-The easiest way to get started with OpnForm is with the [official managed service in the Cloud](https://opnform.com/).
-
-It takes 1 minute to try out the builder for free. You'll have high availability, backups, security, and maintenance all managed for you.
-
-### Requirements
-
--   PHP >= 8.0
--   MySQL/MariaDB or PostgreSQL
--   Node.js and NPM/Yarn/... to compile assets
-
-## Installation
-
-### Environment Setup
-
-Before you can run the application, you need to set up the environment variables. We have provided a script that will automate the process of creating your `.env` files from the provided examples.
-
-Follow these steps to set up your environment:
-
-1. Make sure you have `openssl` installed, as it is required by the setup script to generate secure keys.
-
-2. Run the setup script from the root of the project:
-
-    ```bash
-    chmod +x ./scripts/setup-env.sh
-    ./scripts/setup-env.sh
-    ```
-
-    **If you are using Docker** and want to prepare a Docker-specific environment, run the script with the `--docker` flag:
-
-    ```bash
-    ./scripts/setup-env.sh --docker
-    ```
-
-3. After running the script, review the `.env` and `client/.env` files to ensure all settings are correct for your environment.
-
-Remember to never commit your `.env` files to version control. They should be kept private as they contain sensitive information.
-
-### Docker Installation 🐳
-
-OpnForm can be easily set up using Docker. Pre-built images are available on Docker Hub, which is the recommended method for most users.
-
-#### Prerequisites
-
--   Docker
--   Docker Compose
-
-#### Quick Start
-
-1. Clone the repository:
-
-    ```
-    git clone https://github.com/JhumanJ/OpnForm.git
-    cd OpnForm
-    ```
-
-2. Set up environment files by running the provided setup script. For detailed instructions, refer to the [Environment Setup](#environment-setup) section above:
-
-    ```bash
-    ./scripts/setup-env.sh --docker
-    ```
-
-3. Start the application:
-
-    ```
-    docker-compose up -d
-    ```
-
-4. Access OpnForm at http://localhost
-
-> 🌐 **Server Deployment Note**: When deploying to a server, configure the app URLs in both `.env` and `client/.env` files. Set `APP_URL` in `.env`, and both `NUXT_PUBLIC_APP_URL` & `NUXT_PUBLIC_API_BASE` in `client/.env`.
-
-#### Customization
-
--   **Environment Variables**: Modify `.env` and `client/.env` files to customize your setup. For example, to enable email features, configure a [supported mail driver](https://laravel.com/docs/11.x/mail) in the `.env` file.
-
-#### Upgrading
-
-1. Check the upgrade instructions for your target version in the documentation.
-2. Update your `docker-compose.yml` file if necessary.
-3. Apply changes:
-    ```
-    docker-compose up -d
-    ```
-
-#### Initial Login
-
-After installation, use these credentials to access the admin panel:
-
--   Email: `admin@opnform.com`
--   Password: `password`
-
-⚠️ Change these credentials immediately after your first login.
-
-Note: Public registration is disabled in the self-hosted version. Use the admin account to invite additional users.
-
-#### Building from Source
-
-For development or customization, you can build the Docker images locally:
-
-1. Build the images:
-
-    ```
-    docker build -t opnform-ui:local -f docker/Dockerfile.client .
-    docker build -t opnform-api:local -f docker/Dockerfile.api .
-    ```
-
-2. Create a docker-compose override file:
-
-    ```
-    touch docker-compose.override.yml
-    ```
-
-    Edit the `docker-compose.override.yml` file to use your locally built images:
-
-    ```yaml
-    services:
-        api:
-            image: opnform-api:local
-        ui:
-            image: opnform-ui:local
-        api-worker:
-            image: opnform-api:local
-    ```
-
-3. Start the application:
-    ```
-    docker-compose up -d
-    ```
-
-This method allows you to make changes to the source code and rebuild the images as needed.
-
-#### Clearing all resources
-
-To completely remove all Docker containers, networks, and volumes created by `docker-compose` and also remove all images used by these services, you can use the following command:
-
-```bash
-docker-compose down -v --rmi all
-```
-
-### Using Laravel Valet
-
-This section explains how to get started locally with the project. It's most likely relevant if you're trying to work on the project.
-First, let's work with the codebase and its dependencies.
-
-```bash
-# Get the code!
-git clone git@github.com:JhumanJ/OpnForm.git && cd OpnForm
-
-# Install PHP dependencies
-composer install
-
- # Install JS dependencies
-cd client && npm install
-
-# Compile assets (see the scripts section in package.json)
-npm run dev # or build
-```
-
-Now, we can configure Laravel. We just need to prepare some vars in our `.env` file, just create it with `cp .env.example .env` then open it!
-
-Configure the desired database in the `DATABASE_` section. You can fine tune your installation on the [laravel documentation](https://laravel.com/docs/9.x).
-
-Run these artisan commands:
-
-```bash
-# Generate needed secrets 🙈
-php artisan key:generate
-php artisan jwt:secret # and select yes!
-
-# Creates DB schemas
-php artisan migrate
-```
-
-Now, create an S3 bucket (or equivalent). Create an IAM user with access to this bucket, fill the environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_DEFAULT_REGION`, `AWS_BUCKET`. In your AWS bucket permissions, add the following under "Cross-origin resource sharing (CORS)":
-
-```json
-[
-    {
-        "AllowedHeaders": ["*"],
-        "AllowedMethods": ["PUT", "POST", "GET", "DELETE"],
-        "AllowedOrigins": ["*"],
-        "ExposeHeaders": []
-    }
-]
-```
-
-🎉 Done! Enjoy your personal OpnForm instance at: [http://opnform.test](http://opnform.test).
-
-## One-Click Deployment
-
-[![Deploy to RepoCloud](https://d16t0pc4846x52.cloudfront.net/deploylobe.svg)](https://repocloud.io/details/?app_id=294)
+## Quick Start
 
-## Tech Stack
+The easiest way to get started with OpnForm is through our [official managed service in the Cloud](https://opnform.com/).
 
-OpnForm is a standard web application built with:
+For self-hosted installations, please refer to our [Deployment Guides](https://docs.opnform.com/deployment). For detailed instructions on setting up a local environment, check out our [Local Deployment Documentation](https://docs.opnform.com/deployment/local-deployment).
 
--   [Laravel](https://laravel.com/) PHP framework
--   [NuxtJs](https://nuxt.com/) Front-end SSR framework
--   [Vue.js 3](https://vuejs.org/) Front-end framework
--   [TailwindCSS](https://tailwindcss.com/)
+## Support & Community
 
-## Contribute
+If you need help or have questions, please join our [Discord community](https://discord.gg/YTSjU2a9TS). For more information and assistance, check out the following resources:
 
-You're more than welcome to contribute to this project. We don't have guidelines on this yet, but we will soon. In the meantime, feel free to ask [any question here](https://github.com/JhumanJ/OpnForm/discussions).
+-   [Product Helpdesk](https://help.opnform.com)
+-   [Technical Documentation](https://docs.opnform.com)
 
 ## License
 

client/components/pages/OpenFormFooter.vue

@@ -21,21 +21,6 @@
       </div>
       <div class="flex justify-center mt-5 md:mt-0">
         <div class="grid grid-cols-1 lg:grid-cols-2 gap-x-4 gap-y-2">
-          <template v-if="!useFeatureFlag('self_hosted')">
-            <router-link
-              :to="{ name: 'privacy-policy' }"
-              class="text-gray-600 dark:text-gray-400 transition-colors duration-300 hover:text-nt-blue"
-            >
-              Privacy Policy
-            </router-link>
-
-            <router-link
-              :to="{ name: 'terms-conditions' }"
-              class="text-gray-600 dark:text-gray-400 transition-colors duration-300 hover:text-nt-blue"
-            >
-              Terms & Conditions
-            </router-link>
-          </template>
           <a
             :href="opnformConfig.links.feature_requests"
             target="_blank"
@@ -57,6 +42,28 @@
           >
             Discord
           </a>
+          <a
+            :href="opnformConfig.links.tech_docs"
+            target="_blank"
+            class="text-gray-600 dark:text-gray-400 transition-colors duration-300 hover:text-nt-blue"
+          >
+            Technical Docs
+          </a>
+          <template v-if="!useFeatureFlag('self_hosted')">
+            <router-link
+              :to="{ name: 'privacy-policy' }"
+              class="text-gray-600 dark:text-gray-400 transition-colors duration-300 hover:text-nt-blue"
+            >
+              Privacy Policy
+            </router-link>
+
+            <router-link
+              :to="{ name: 'terms-conditions' }"
+              class="text-gray-600 dark:text-gray-400 transition-colors duration-300 hover:text-nt-blue"
+            >
+              Terms & Conditions
+            </router-link>
+          </template>
         </div>
       </div>
     </div>

client/opnform.config.js

@@ -16,5 +16,6 @@ export default {
     feature_requests: "https://feedback.opnform.com/",
     changelog_url: "https://feedback.opnform.com/changelog",
     roadmap: "https://feedback.opnform.com/roadmap",
+    tech_docs: "https://docs.opnform.com",
   },
 }

client/public/img/social-preview.jpg

@@ -0,0 +1,4 @@
+---
+title: "List Forms"
+openapi: "GET /external/zapier/forms"
+---

docs/api-reference/endpoint/list-forms.mdx

@@ -0,0 +1,4 @@
+---
+title: "New Submission Trigger"
+openapi: "POST /external/zapier/webhook"
+---

docs/api-reference/endpoint/new-submission-trigger.mdx

@@ -0,0 +1,4 @@
+---
+title: "Sample Submission Polling"
+openapi: "GET /external/zapier/submissions/recent"
+---

docs/api-reference/endpoint/sample-submission-polling.mdx

@@ -0,0 +1,4 @@
+---
+title: "Unsubscribe Webhook"
+openapi: "DELETE /external/zapier/webhook"
+---

docs/api-reference/endpoint/unsubscribe-webhook.mdx

@@ -0,0 +1,4 @@
+---
+title: "Validate API Key"
+openapi: "GET /external/zapier/validate"
+---

docs/api-reference/endpoint/validate-api-key.mdx

@@ -0,0 +1,37 @@
+---
+title: "Introduction"
+description: "API Documentation for OpnForm"
+---
+
+Welcome to the OpnForm API documentation. This guide provides information on how to interact with the OpnForm API to automate your workflows and integrate OpnForm with your applications.
+
+## Authentication
+
+To authenticate with the OpnForm API, you need an API key. Here's how to create and use an API key.
+
+### Creating an API Key
+
+<Frame>
+  <img
+    src="/api-reference/images/create-token.png"
+    alt="Creating an API Key in OpnForm"
+  />
+</Frame>
+
+1. Log in to your OpnForm account.
+2. Navigate to the Access Tokens page at https://opnform.com/settings/access-tokens.
+3. Click on the "Create new token" button.
+4. Give your token a name (e.g., "My API Integration").
+5. Click "Create" to generate your API key. 6. Copy the generated API key immediately, as it won't be displayed again for security reasons.
+
+### Using the API Key
+
+To use the API key, you need to include it in the header of every request you make to the API as a Bearer token. Here's how to do it:
+
+1. Take your API key that you generated earlier.
+2. Add it to the `Authorization` header of your HTTP request.
+3. Prefix the key with the word "Bearer" followed by a space.
+
+```
+Authorization: Bearer YOUR_API_KEY
+```