diff --git a/README.md b/README.md index e31f6747..d1e4937c 100644 --- a/README.md +++ b/README.md @@ -20,244 +20,37 @@ Rewarded Bounties

-> 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). - - - - Bounties of OpnForm - - - -## 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 diff --git a/client/components/open/forms/fields/components/FieldOptions.vue b/client/components/open/forms/fields/components/FieldOptions.vue index dbfb1a73..f6508422 100644 --- a/client/components/open/forms/fields/components/FieldOptions.vue +++ b/client/components/open/forms/fields/components/FieldOptions.vue @@ -295,6 +295,7 @@ Advanced options for your select/multiselect fields.

option.name).join('\n') + }, prefillSelectsOptions() { if (!['select', 'multi_select'].includes(this.field.type)) return {} diff --git a/client/components/pages/OpenFormFooter.vue b/client/components/pages/OpenFormFooter.vue index 431b423f..f9446d26 100644 --- a/client/components/pages/OpenFormFooter.vue +++ b/client/components/pages/OpenFormFooter.vue @@ -21,21 +21,6 @@
- Discord + + Technical Docs + +
diff --git a/client/components/pages/pricing/PricingTable.vue b/client/components/pages/pricing/PricingTable.vue index 6f85b4bc..fe558432 100644 --- a/client/components/pages/pricing/PricingTable.vue +++ b/client/components/pages/pricing/PricingTable.vue @@ -212,6 +212,7 @@ export default { "Larger file uploads (50mb)", "Remove OpnForm branding", "Priority support", + "Form Analytics" ], }), diff --git a/client/opnform.config.js b/client/opnform.config.js index e749d6a4..eb92fb6e 100644 --- a/client/opnform.config.js +++ b/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", }, } diff --git a/client/public/img/social-preview.jpg b/client/public/img/social-preview.jpg index 53b5b04d..efd3edde 100644 Binary files a/client/public/img/social-preview.jpg and b/client/public/img/social-preview.jpg differ diff --git a/docs/README.MD b/docs/README.MD new file mode 100644 index 00000000..625c708c --- /dev/null +++ b/docs/README.MD @@ -0,0 +1,9 @@ +# Development + +Install the Mintlify CLI to preview the documentation changes locally. To install, use the following command + +`npm i -g mintlify` + +Run the following command at the root of your documentation (where mint.json is) + +`mintlify dev` diff --git a/docs/api-reference/endpoint/list-forms.mdx b/docs/api-reference/endpoint/list-forms.mdx new file mode 100644 index 00000000..22745a15 --- /dev/null +++ b/docs/api-reference/endpoint/list-forms.mdx @@ -0,0 +1,4 @@ +--- +title: "List Forms" +openapi: "GET /external/zapier/forms" +--- diff --git a/docs/api-reference/endpoint/new-submission-trigger.mdx b/docs/api-reference/endpoint/new-submission-trigger.mdx new file mode 100644 index 00000000..35001205 --- /dev/null +++ b/docs/api-reference/endpoint/new-submission-trigger.mdx @@ -0,0 +1,4 @@ +--- +title: "New Submission Trigger" +openapi: "POST /external/zapier/webhook" +--- diff --git a/docs/api-reference/endpoint/sample-submission-polling.mdx b/docs/api-reference/endpoint/sample-submission-polling.mdx new file mode 100644 index 00000000..87d8fdd4 --- /dev/null +++ b/docs/api-reference/endpoint/sample-submission-polling.mdx @@ -0,0 +1,4 @@ +--- +title: "Sample Submission Polling" +openapi: "GET /external/zapier/submissions/recent" +--- diff --git a/docs/api-reference/endpoint/unsubscribe-webhook.mdx b/docs/api-reference/endpoint/unsubscribe-webhook.mdx new file mode 100644 index 00000000..100ab70c --- /dev/null +++ b/docs/api-reference/endpoint/unsubscribe-webhook.mdx @@ -0,0 +1,4 @@ +--- +title: "Unsubscribe Webhook" +openapi: "DELETE /external/zapier/webhook" +--- diff --git a/docs/api-reference/endpoint/validate-api-key.mdx b/docs/api-reference/endpoint/validate-api-key.mdx new file mode 100644 index 00000000..df6eef29 --- /dev/null +++ b/docs/api-reference/endpoint/validate-api-key.mdx @@ -0,0 +1,4 @@ +--- +title: "Validate API Key" +openapi: "GET /external/zapier/validate" +--- diff --git a/docs/api-reference/images/create-token.png b/docs/api-reference/images/create-token.png new file mode 100644 index 00000000..c6b10445 Binary files /dev/null and b/docs/api-reference/images/create-token.png differ diff --git a/docs/api-reference/introduction.mdx b/docs/api-reference/introduction.mdx new file mode 100644 index 00000000..60df239d --- /dev/null +++ b/docs/api-reference/introduction.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 + + + Creating an API Key in OpnForm + + +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 +``` diff --git a/docs/api-reference/openapi.json b/docs/api-reference/openapi.json new file mode 100644 index 00000000..7d1f7c7b --- /dev/null +++ b/docs/api-reference/openapi.json @@ -0,0 +1,200 @@ +{ + "openapi": "3.0.1", + "info": { + "title": "OpnForm API", + "description": "API for interacting with OpnForm, primarily used for Zapier integration", + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://api.opnform.com" + } + ], + "security": [ + { + "bearerAuth": [] + } + ], + "paths": { + "/external/zapier/validate": { + "get": { + "summary": "Validate API Key", + "description": "This endpoint is used by Zapier to test the validity of the API key.", + "responses": { + "200": { + "description": "API key is valid" + }, + "401": { + "description": "Invalid API key" + } + } + } + }, + "/external/zapier/forms": { + "get": { + "summary": "List Forms", + "description": "Retrieve a list of forms available in a specific workspace.", + "parameters": [ + { + "name": "workspace_id", + "in": "query", + "description": "The ID of the workspace for which to list forms", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Form" + } + } + } + } + } + } + } + }, + "/external/zapier/webhook": { + "post": { + "summary": "New Submission Trigger", + "description": "This endpoint is used to set up a webhook for new form submissions.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "hookUrl": { + "type": "string", + "description": "The URL provided by Zapier to send the submission data" + }, + "form_id": { + "type": "string", + "description": "The ID of the form for which to trigger the webhook" + } + }, + "required": ["hookUrl", "form_id"] + } + } + } + }, + "responses": { + "200": { + "description": "Webhook successfully set up" + } + } + }, + "delete": { + "summary": "Unsubscribe Webhook", + "description": "This endpoint is used to unsubscribe from the webhook.", + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "hookUrl": { + "type": "string", + "description": "The URL provided by Zapier to stop sending the submission data" + }, + "form_id": { + "type": "string", + "description": "The ID of the form for which to unsubscribe the webhook" + } + }, + "required": ["hookUrl", "form_id"] + } + } + } + }, + "responses": { + "200": { + "description": "Webhook successfully unsubscribed" + } + } + } + }, + "/external/zapier/submissions/recent": { + "get": { + "summary": "Sample Submission Polling", + "description": "Retrieves the most recent submissions for a specified form.", + "parameters": [ + { + "name": "form_id", + "in": "query", + "description": "The ID of the form to retrieve submissions for", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Successful response", + "content": { + "application/json": { + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Submission" + } + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "Form": { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } + } + }, + "Submission": { + "type": "object", + "properties": { + "submission_id": { + "type": "string" + }, + "form_id": { + "type": "string" + }, + "submitted_at": { + "type": "string", + "format": "date-time" + }, + "data": { + "type": "object", + "additionalProperties": true + } + } + } + }, + "securitySchemes": { + "bearerAuth": { + "type": "http", + "scheme": "bearer" + } + } + } +} \ No newline at end of file diff --git a/docs/configuration/aws-s3.mdx b/docs/configuration/aws-s3.mdx new file mode 100644 index 00000000..caa69037 --- /dev/null +++ b/docs/configuration/aws-s3.mdx @@ -0,0 +1,30 @@ +--- +title: AWS S3 Configuration +description: OpnForm & File uploads +--- + +OpnForm uses [Laravel's filesystem](https://laravel.com/docs/master/filesystem), which provides a powerful abstraction layer for various file storage systems. While AWS S3 is a popular choice, OpnForm supports both local storage and S3-compatible services. + +1. Create an S3 bucket in your AWS account (or use an equivalent service). + +2. Create an IAM user with access to this bucket. Ensure the user has the necessary permissions to read from and write to the bucket. + +3. Configure CORS for the S3 bucket permissions, by adding the following under "Cross-origin resource sharing (CORS)": + ```json + [ + { + "AllowedHeaders": ["*"], + "AllowedMethods": ["PUT", "POST", "GET", "DELETE"], + "AllowedOrigins": ["*"], + "ExposeHeaders": [] + } + ] + ``` + +4. Set the following environment variables in your OpnForm installation (`api/.env`): + - `AWS_ACCESS_KEY_ID`: Your IAM user's access key ID + - `AWS_SECRET_ACCESS_KEY`: Your IAM user's secret access key + - `AWS_DEFAULT_REGION`: The AWS region where your S3 bucket is located + - `AWS_BUCKET`: The name of your S3 bucket + +These settings will enable OpnForm to use your S3 bucket for file storage. diff --git a/docs/configuration/custom-domain.mdx b/docs/configuration/custom-domain.mdx new file mode 100644 index 00000000..8ee913cd --- /dev/null +++ b/docs/configuration/custom-domain.mdx @@ -0,0 +1,20 @@ +--- +title: Using your own domain +description: Setting up a custom domain for OpnForm +--- + +This page explains how to configure a custom domain for your OpnForm instance. +## Custom Domain Setup + +To use a custom domain (or subdomain)with OpnForm: + +1. Purchase a domain (if needed) +2. Configure DNS records to point to your OpnForm instance +3. Update OpnForm configuration: + - Set `APP_URL` in `.env` + - Set `NUXT_PUBLIC_APP_URL` and `NUXT_PUBLIC_API_BASE` in `client/.env` +4. Secure with SSL certificate + +import CloudVersion from "/snippets/cloud-version.mdx"; + + \ No newline at end of file diff --git a/docs/configuration/email-setup.mdx b/docs/configuration/email-setup.mdx new file mode 100644 index 00000000..726c44b1 --- /dev/null +++ b/docs/configuration/email-setup.mdx @@ -0,0 +1,33 @@ +--- +title: Email Setup +description: OpnForm & Emails +--- + +This page explains how to configure email notifications in OpnForm. + +By default, with a new Docker deployment, the email driver used is `log`, which simply logs the emails instead of sending them. To enable actual email sending, you need to set up a proper email configuration. + +OpnForm uses Laravel's mail system. For more detailed information, you can refer to the [Laravel Mail documentation](https://laravel.com/docs/master/mail). + +## Supported Mail Drivers + +Laravel supports various mail drivers, including SMTP, Mailgun, Postmark, Amazon SES, and more. In this guide, we'll focus on setting up SMTP, which is widely used. + +## Configuring SMTP Settings + +To configure SMTP, you need to set the following environment variables in your `.env` file: + +| Variable | Description | +|----------|-------------| +| `MAIL_MAILER` | Set this to `smtp` to use the SMTP driver. | +| `MAIL_HOST` | The address of your SMTP server. | +| `MAIL_PORT` | The port used by your SMTP server (common ports are 25, 465, and 587). | +| `MAIL_USERNAME` | The username for your SMTP account. | +| `MAIL_PASSWORD` | The password for your SMTP account. | +| `MAIL_ENCRYPTION` | The encryption method used by your SMTP server (typically `tls` or `ssl`). | +| `MAIL_FROM_ADDRESS` | The email address that emails should be sent from. | +| `MAIL_FROM_NAME` | The name that should appear as the sender of the emails. | + +import CloudVersion from "/snippets/cloud-version.mdx"; + + \ No newline at end of file diff --git a/docs/configuration/environment-variables.mdx b/docs/configuration/environment-variables.mdx new file mode 100644 index 00000000..8972657d --- /dev/null +++ b/docs/configuration/environment-variables.mdx @@ -0,0 +1,64 @@ +--- +title: Environment Variables Configuration +description: Detailed guide on configuring environment variables for OpnForm +--- + +OpnForm uses two `.env` files for configuration: one for the Laravel backend located in the `api` directory, and one for the Nuxt front-end located in the `client` directory. + +## Backend Environment Variables + +The following environment variables are used to [configure the Laravel](https://laravel.com/docs/11.x/configuration) application (OpnForm's API). + +### Dedicated guides +There are dedicated configuration pages available for more detailed setup instructions on specific topics: +- [File Storage (S3)](../configuration/aws-s3) +- [Email Configuration (SMTP)](../configuration/email-setup) +- [Custom Domain](../configuration/custom-domain) + + +### Other Environment Variables + +### Configuration Environment Variables + +| Variable Name | Description | +|------------------------------|--------------------------------------------------| +| `JWT_TTL` | Time to live for JSON Web Tokens (JWT). | +| `JWT_SECRET` | Secret key used to sign JWTs. | +| `H_CAPTCHA_SITE_KEY` | Site key for hCaptcha integration. | +| `H_CAPTCHA_SECRET_KEY` | Secret key for hCaptcha integration. | +| `OPEN_AI_API_KEY` | API key for accessing OpenAI services. | +| `UNSPLASH_ACCESS_KEY` | Access key for Unsplash API. | +| `UNSPLASH_SECRET_KEY` | Secret key for Unsplash API. | +| `GOOGLE_CLIENT_ID` | Client ID for Google OAuth. | +| `GOOGLE_CLIENT_SECRET` | Client secret for Google OAuth. | +| `GOOGLE_REDIRECT_URL` | Redirect URL for Google OAuth. | +| `GOOGLE_AUTH_REDIRECT_URL` | Authentication redirect URL for Google OAuth. | +| `GOOGLE_FONTS_API_KEY` | API key for accessing Google Fonts. | +| `FRONT_URL` | Public facing URL of the front-end. | +| `FRONT_API_SECRET` | Shared secret with the front-end. | + +### User Options Environment Variables + +| Variable Name | Description | +|------------------------------|--------------------------------------------------| +| `ADMIN_EMAILS` | Comma-separated list of admin email addresses. | +| `TEMPLATE_EDITOR_EMAILS` | Comma-separated list of template editor emails. | +| `EXTRA_PRO_USERS_EMAILS` | Comma-separated list of extra pro user emails. | +| `MODERATOR_EMAILS` | Comma-separated list of moderator email addresses. | + + +## Front-end Environment Variables + +### Front-end Environment Variables + +| Variable Name | Description | +|------------------------------|--------------------------------------------------| +| `NUXT_PUBLIC_APP_URL` | Public facing URL of the Nuxt application. | +| `NUXT_PUBLIC_API_BASE` | Base URL for the Laravel API. | +| `NUXT_PUBLIC_H_CAPTCHA_SITE_KEY` | Site key for hCaptcha integration on the front-end. | +| `NUXT_API_SECRET` | Shared secret key between Nuxt and Laravel backend. | + + +import CloudVersion from "/snippets/cloud-version.mdx"; + + \ No newline at end of file diff --git a/docs/contributing/bounties.mdx b/docs/contributing/bounties.mdx new file mode 100644 index 00000000..4e0063dc --- /dev/null +++ b/docs/contributing/bounties.mdx @@ -0,0 +1,10 @@ +# Bounties + +This page will explain the bounty system for OpnForm contributions. + +Topics include: + +- How the bounty system works +- Current open bounties +- How to claim a bounty +- Payout process diff --git a/docs/contributing/getting-started.mdx b/docs/contributing/getting-started.mdx new file mode 100644 index 00000000..0c4df6f2 --- /dev/null +++ b/docs/contributing/getting-started.mdx @@ -0,0 +1,20 @@ +--- +title: "Getting Started with Contributing" +description: "Learn how to contribute to OpnForm" +--- + +Welcome to the OpnForm contributing guide! Here are some helpful links to get you started: + + + + Learn how to configure the environment variables for OpnForm. + + + Follow the steps to add a new form block to your project. + + + Discover how to integrate new services with OpnForm. + + + +We sometimes offer bounties for certain issues. Check out our [bounties page](https://console.algora.io/org/OpnForm) for more information. diff --git a/docs/contributing/new-form-block.mdx b/docs/contributing/new-form-block.mdx new file mode 100644 index 00000000..11ee32d7 --- /dev/null +++ b/docs/contributing/new-form-block.mdx @@ -0,0 +1,6 @@ +--- +title: "Creating a New Form Block" +description: "Learn how to create a new form block for OpnForm" +--- + +Whoops not ready yet! This page is still to be written. \ No newline at end of file diff --git a/docs/contributing/new-integration.mdx b/docs/contributing/new-integration.mdx new file mode 100644 index 00000000..87c048e0 --- /dev/null +++ b/docs/contributing/new-integration.mdx @@ -0,0 +1,6 @@ +--- +title: "Adding a New Integration" +description: "Learn how to add a new integration to OpnForm" +--- + +Whoops not ready yet! This page is still to be written. \ No newline at end of file diff --git a/docs/deployment/cloud-vs-self-hosting.mdx b/docs/deployment/cloud-vs-self-hosting.mdx new file mode 100644 index 00000000..d8d85a48 --- /dev/null +++ b/docs/deployment/cloud-vs-self-hosting.mdx @@ -0,0 +1,34 @@ +--- +title: "Cloud vs Self-Hosting" +description: "Understand the differences between cloud and self-hosting options for OpnForm" +--- + +When deciding between using OpnForm's cloud service or self-hosting, it's important to understand the key differences and benefits of each option. Below is a comparison to help you make an informed decision: + +| | Self-Hosted | OpnForm Cloud | +| ------------------------------ | ----------------------------------- | ---------------------------------- | +| High availability servers | \~$50+/month | ✅ | +| Load balancer | \~$15+/month | ✅ | +| Managed database | \~$45-70+/month | ✅ | +| SMTP server | \~$15+/month | ✅ | +| Support | Discord | Live Chat | +| Setup time | Manual | ✅ Up and running in minutes | +| Upgrades | Manual | ✅ Automatic | +| Multi-zone availability | Manual | ✅ | +| Backups | Manual | ✅ Automatic | +| Monitoring | Manual | ✅ | +| Custom code and forks | ✅ | ❌ | +| SSL certificate | Manual | ✅ | +| Where your money goes | 3rd-party services | Improving OpnForm | + +### When Should You Self-Host? + +There are specific scenarios where self-hosting OpnForm might be the better choice: + +- **Regulatory Compliance**: If you need an air-gapped environment for regulatory reasons (e.g., HIPAA compliance). +- **Custom Builds**: If you want to run a custom build or fork of OpnForm with your own customizations. +- **Custom Integrations**: If you need to use community or custom integrations that are not supported in the cloud version. + +For most users, the managed OpnForm Cloud service will be the better option due to its ease of use, automatic updates, and comprehensive support. + +*This comparison is inspired by the [Metabase Cloud vs Self-Hosting page](https://www.metabase.com/docs/latest/cloud/cloud-vs-self-hosting).* diff --git a/docs/deployment/docker.mdx b/docs/deployment/docker.mdx new file mode 100644 index 00000000..e6b94940 --- /dev/null +++ b/docs/deployment/docker.mdx @@ -0,0 +1,94 @@ +--- +title: "Docker" +description: "OpnForm can be easily set up using Docker. We provide pre-built images on Docker Hub, which is the recommended method for most users." +--- + +import CloudVersion from "/snippets/cloud-version.mdx"; + + + +## Prerequisites + +- Docker +- Docker Compose + +## Quick Start + +1. Clone the repository: + + ```bash + git clone https://github.com/JhumanJ/OpnForm.git + cd OpnForm + ``` + +2. Set up environment files: + + ```bash + ./scripts/setup-env.sh --docker + ``` + +3. (Optional) Customize the environment variables: + + You can modify two environment files to customize your OpnForm installation: + - The `.env` file in the `api` directory for backend configuration + - The `.env` file in the `client` directory for frontend configuration + + For more information on available environment variables, please refer to our [Environment Variables](/configuration/environment-variables) page. + +4. Start the application: + + ```bash + docker-compose up -d + ``` + +5. Access OpnForm at http://localhost + + +## Docker Images + +OpnForm provides pre-built Docker images for easy deployment. You can find our official Docker images on Docker Hub: + +- [OpnForm API Image](https://hub.docker.com/r/jhumanj/opnform-api) +- [OpnForm Client Image](https://hub.docker.com/r/jhumanj/opnform-client) + +We recommend using these official images for your OpnForm deployment. + + +## Building Your Own Docker Images + +If you prefer to build your own Docker images, you can do so using the provided Dockerfiles in the repository: + +1. Build the API image: + ```bash + docker build -t opnform-api:local -f docker/Dockerfile.api . + ``` + +2. Build the UI image: + ```bash + docker build -t opnform-ui:local -f docker/Dockerfile.client . + ``` + +### Overriding Docker Compose Configuration + +You can override the default Docker Compose configuration by creating a `docker-compose.override.yml` file. This allows you to customize various aspects of the deployment without modifying the main `docker-compose.yml` file. + +Example `docker-compose.override.yml`: + +```yaml +services: + api: + image: opnform-api:local + ui: + image: opnform-ui:local + api-worker: + image: opnform-api:local +``` + + +### 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: + +``` +docker-compose down -v --rmi all +``` diff --git a/docs/deployment/local-deployment.mdx b/docs/deployment/local-deployment.mdx new file mode 100644 index 00000000..10e84c64 --- /dev/null +++ b/docs/deployment/local-deployment.mdx @@ -0,0 +1,64 @@ +--- +title: "Local Deployment" +description: "Set up OpnForm locally for development" +--- + +import CloudVersion from "/snippets/cloud-version.mdx"; + + + +## Requirements + +Before proceeding with the local deployment, ensure you have the following prerequisites installed on your system: + +- **PHP**: Version 8.0 or higher +- **Composer**: The PHP dependency manager +- **Node.js**: Version 14 or higher +- **NPM** or **Yarn**: Package managers for Node.js +- **MySQL**, or **PostgreSQL**: A supported database system + +Make sure these components are properly installed and configured on your local machine before proceeding with the deployment steps. + +## Local setup + +1. Install Laravel Herd -Download and install Laravel Herd from the official website: https://herd.laravel.com/ + +2. Clone the repository and install dependencies: + + ```bash + git clone git@github.com:JhumanJ/OpnForm.git && cd OpnForm + cd api && composer install + cd ../client && npm install + ``` + +3. Compile assets and run dev server: + + ```bash + cd client && npm run dev # or build + ``` + +4. Set up environment files: + + ```bash + ./scripts/setup-env.sh + ``` + This script will create the necessary `.env` files for both the API and client. + +5. Run the migrations: + + ```bash + cd api + php artisan migrate + ``` + +6. Set up Herd: + For detailed instructions on setting up Herd, refer to the [Herd documentation](https://herd.laravel.com/docs). + - Open the Herd application + - Add your OpnForm's `api` directory to Herd + - Herd will automatically configure a local domain for your project + + This will start the Nuxt.js development server, typically on `http://localhost:3000`. + +8. Access your local OpnForm installation: + - The API will be available at the domain provided by Herd (e.g., `http://opnform.test`) + - The frontend will be accessible at `http://localhost:3000` diff --git a/docs/favicon.ico b/docs/favicon.ico new file mode 100644 index 00000000..7ae1b820 Binary files /dev/null and b/docs/favicon.ico differ diff --git a/docs/favicon.svg b/docs/favicon.svg new file mode 100644 index 00000000..6a323326 --- /dev/null +++ b/docs/favicon.svg @@ -0,0 +1,49 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/checks-passed.png b/docs/images/checks-passed.png new file mode 100644 index 00000000..3303c773 Binary files /dev/null and b/docs/images/checks-passed.png differ diff --git a/docs/images/hero-dark.svg b/docs/images/hero-dark.svg new file mode 100644 index 00000000..c6a30e88 --- /dev/null +++ b/docs/images/hero-dark.svg @@ -0,0 +1,161 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/images/hero-light.svg b/docs/images/hero-light.svg new file mode 100644 index 00000000..297d68fb --- /dev/null +++ b/docs/images/hero-light.svg @@ -0,0 +1,155 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/logo.svg b/docs/logo.svg new file mode 100644 index 00000000..70562a4b --- /dev/null +++ b/docs/logo.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/mint.json b/docs/mint.json new file mode 100644 index 00000000..bf78aa3b --- /dev/null +++ b/docs/mint.json @@ -0,0 +1,122 @@ +{ + "$schema": "https://mintlify.com/schema.json", + "name": "OpnForm Technical Docs", + "logo": { + "light": "/logo.svg", + "dark": "/logo.svg" + }, + "favicon": "/logo.svg", + "colors": { + "primary": "#3b82f6", + "light": "#60a5fa", + "dark": "#2563eb", + "anchors": { + "from": "#2563eb", + "to": "#60a5fa" + } + }, + "topbarLinks": [ + { + "name": "OpnForm", + "url": "https://opnform.com?utm_source=docs&utm_medium=topbar&utm_campaign=technical_docs" + }, + { + "name": "GitHub", + "url": "https://github.com/JhumanJ/OpnForm" + } + ], + "topbarCtaButton": { + "name": "Dashboard", + "url": "https://opnform.com" + }, + "tabs": [ + { + "name": "API Reference", + "url": "api-reference" + }, + { + "name": "Contributing", + "url": "contributing" + } + ], + "anchors": [ + { + "name": "Product Documentation", + "icon": "book-open-cover", + "url": "https://help.opnform.com" + }, + { + "name": "Community", + "icon": "discord", + "url": "https://discord.gg/YTSjU2a9TS" + }, + { + "name": "Changelog", + "icon": "sparkles", + "url": "https://feedback.opnform.com/changelog" + }, + { + "name": "Roadmap", + "icon": "road", + "url": "https://feedback.opnform.com/roadmap" + } + ], + "navigation": [ + { + "group": "Get Started", + "pages": [ + "introduction", + "tech-stack" + ] + }, + { + "group": "Deployment", + "pages": [ + "deployment/docker", + "deployment/local-deployment", + "deployment/cloud-vs-self-hosting" + ] + }, + { + "group": "Configuration", + "pages": [ + "configuration/environment-variables", + "configuration/aws-s3", + "configuration/email-setup", + "configuration/custom-domain" + ] + }, + { + "group": "API Reference", + "pages": [ + "api-reference/introduction" + ] + }, + { + "group": "Zapier Endpoints", + "pages": [ + "api-reference/endpoint/validate-api-key", + "api-reference/endpoint/list-forms", + "api-reference/endpoint/new-submission-trigger", + "api-reference/endpoint/unsubscribe-webhook", + "api-reference/endpoint/sample-submission-polling" + ] + }, + { + "group": "Contributing", + "pages": [ + "contributing/getting-started", + "contributing/new-form-block", + "contributing/new-integration" + ] + } + ], + "footerSocials": { + "twitter": "https://twitter.com/opnform", + "github": "https://github.com/JhumanJ/OpnForm" + }, + "openapi": "/api-reference/openapi.json", + "feedback": { + "suggestEdit": true + } +} \ No newline at end of file diff --git a/docs/snippets/cloud-version.mdx b/docs/snippets/cloud-version.mdx new file mode 100644 index 00000000..161e3a5c --- /dev/null +++ b/docs/snippets/cloud-version.mdx @@ -0,0 +1,3 @@ + +The easiest way to get started with OpnForm is through our [official managed service in the Cloud](https://opnform.com/?utm_source=docs&utm_medium=introduction&utm_campaign=cloud_version). It takes just 1 minute to try out the builder for free, with high availability, backups, security, and maintenance all managed for you. + diff --git a/docs/tech-stack.mdx b/docs/tech-stack.mdx new file mode 100644 index 00000000..fc12635e --- /dev/null +++ b/docs/tech-stack.mdx @@ -0,0 +1,63 @@ +--- +title: "Tech Stack" +description: "Overview of OpnForm's technology stack" +--- + +OpnForm is built using a modern and robust technology stack, ensuring high performance, scalability, and maintainability. Here's an overview of the main technologies used in the project: + +## Backend + + + Version 8.0 or higher, powering the core backend functionality. + + + + The PHP framework that powers the backend of OpnForm. + + +## Database + + + Supports relational database management systems like MySQL/MariaDB and PostgreSQL. + + +## Frontend + + + The progressive JavaScript framework used for building the user interface. + + + + The Vue.js framework that enables server-side rendering and other powerful features. + + + + A utility-first CSS framework for rapidly building custom user interfaces. + + +## Asset Compilation + + + Used for running JavaScript tools in the development environment. + + + + Package manager for installing and managing frontend dependencies. + + +## Additional Technologies + + + Containerization platform used for easy deployment and development setup. + + + + In-memory data structure store, used for caching and as a message broker. + + + + Used for file storage (or compatible alternatives). + + +This tech stack allows OpnForm to deliver a fast, responsive, and feature-rich form building experience. For detailed installation instructions and system requirements, please refer to our [Docker deployment guide](deployment/docker) or [Local deployment guide](deployment/local-deployment). +