# Setting up a dev environment

{% hint style="info" %}
It's worth noting that the [Enterprise](https://formsort.com/pricing/) plan is the only one that allows access to multiple environments (staging, dev, etc.). If you are on the Free or Pro plans, this guide will still be helpful, but you will have to test with your Production environments. If you're interested in upgrading to Enterprise, chat us on Intercom! 
{% endhint %}

It's not uncommon to want to host your form on your own application, and using our [web-embed](https://docs.formsort.com/publishing-and-deployment/embedding/web-embed-api) capabilities will allow you to do this. But it's also important to have a safe environment to troubleshoot your embed page, or even experiment with different configurations without affecting the production flow. 

Your first instinct (probably) is to set up a dev environment by serving up your embedding page on localhost and testing there, but there are two caveats with Formsort flows - any domain your flow is embedded into needs to be [whitelisted](https://docs.formsort.com/publishing-and-deployment/embedding/..#whitelisting-embedding-domains) in your studio, and localhost cannot be whitelisted.

{% hint style="warning" %}
Whitelisting is required to prevent unknown domains from hosting your flow, with the added benefit that the parent page will have access to the user’s submission data.
{% endhint %}

If your embedding domain is not whitelisted in Formsort, the flow will not display on the page, and you’ll likely see a `CSP: "frame-ancestor"` error.

<figure><img src="https://1036686854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJPnL__mOdr_mLZ8nwf%2Fuploads%2F0aPszSTJmrB56kf96DcU%2FWL_error.png?alt=media&#x26;token=4495d0c3-6086-4e0d-b6fd-59081ab2a2aa" alt=""><figcaption><p>Trying to frame in an unlisted domain</p></figcaption></figure>

The process here is to use a proxy, like [ngrok](https://ngrok.com/product), which will make your **localhost** environment available on the internet by providing a forwarding address. This address *can* be whitelisted in Formsort.&#x20;

{% hint style="info" %}
We suggest using nrgok because the basic service is free and is quick and easy to install, but feel free to use any proxy you're familiar with.&#x20;
{% endhint %}

This guide will show you how to get your dev environment set up and whitelist the required subdomain.&#x20;

## Getting Setup

#### What you’ll need:

* The correct [roles and permissions](https://docs.formsort.com/workspace-management/accounts/roles-and-permissions) for your Formsort studio account
  * **Owner**, **Admin**, and **Engineer** all have the requisite permissions
* A place to send test data
* The embed code for your flow
  * see our [embed-docs](https://github.com/formsort/oss/tree/master/packages/web-embed-api#formsortweb-embed-api) for getting set up here
* If you're planning on using ngrok specifically, a free [ngrok account](https://ngrok.com/)

### 1. Create your environment

In order to receive test data at your integration targets, you’ll need to create integrations specific to the test environment.

* Create a “dev” environment in the **Integrations** menu of the flow you are going to be working in.

{% hint style="info" %}
Making a "dev" environment is optional. At your own discretion, you can opt for the **staging** environment instead. However, we suggest creating a third environment so that any developers have their own space and integration set to test with.&#x20;
{% endhint %}

<figure><img src="https://1036686854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJPnL__mOdr_mLZ8nwf%2Fuploads%2F5nQ1p3bkda4GcJ1otW87%2Fadd_env.png?alt=media&#x26;token=b9e00fbe-8bdd-4372-8f88-80a3a915aaea" alt=""><figcaption><p>Add "dev" in the "Edits environment" menu</p></figcaption></figure>

* Setup your integration target(s) in this new dev environment. Be sure to save your changes!&#x20;

<figure><img src="https://1036686854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJPnL__mOdr_mLZ8nwf%2Fuploads%2FgMs1KJgxUAJThoPyQX2L%2Finteg_set_dev.png?alt=media&#x26;token=8fae234f-a97c-42f2-97d4-2bcf25fb08b1" alt=""><figcaption><p>Setting up a webhook target for the dev environment</p></figcaption></figure>

* Head into a variant you want to use and [deploy](https://docs.formsort.com/core-concepts/versioning-in-formsort-deploying) it to your "dev" environment.

<figure><img src="https://1036686854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJPnL__mOdr_mLZ8nwf%2Fuploads%2F1VvFmFSG7dqVy1iggjCv%2Fdeploy_env.png?alt=media&#x26;token=d1e83cd3-072f-4f33-9603-214af6a979c2" alt=""><figcaption><p>Select your dev environment and then ship that sucker </p></figcaption></figure>

### 2. Configure your embed&#x20;

Now, you’ll need to write the code instruction to load your flow into the new developer environment.

* Have the embed configuration pass in `formsortEnv=dev` as a query parameter.

The syntax for the query parameter here requires an array of string values. Below is the code for an example functional component in React:

<figure><img src="https://1036686854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJPnL__mOdr_mLZ8nwf%2Fuploads%2FbqWz4yB6GQdzaaAcGESM%2Fembed_code.png?alt=media&#x26;token=72b51b63-77e6-4ee1-9a6c-8e2e59fbbbfb" alt=""><figcaption><p>The clientLabel and flowLabel props are also required, in any case</p></figcaption></figure>

This will allow the variant to load in the dev environment.

{% hint style="info" %}
See our [embed docs](https://docs.formsort.com/publishing-and-deployment/embedding/web-embed-api) for more information about code requirements and syntax.&#x20;
{% endhint %}

### 3. Install ngrok&#x20;

If you don’t already have ngrok available, install it in the root project folder. You can see installation instructions [on their official site](https://ngrok.com/docs/getting-started#step-2-install-the-ngrok-agent).

{% hint style="info" %}
Steps 2 and 3 in the ngrok install guide are sufficient to get the client installed.&#x20;
{% endhint %}

### 4. Whitelist the embedding domain

Now we need to whitelist ngrok in your Formsort studio. Head to **Setup** -> **Security** in the left toolbar of your Studio view.

If you’re using the freemium version of ngrok, the easiest thing to do here would be to whitelist using a wildcard subdomain: `*.ngrok.io`. This is because ngrok will serve you a different subdomain every time you run the service.

If you already have a dedicated ngrok/proxy address, whitelist that instead.

<figure><img src="https://1036686854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJPnL__mOdr_mLZ8nwf%2Fuploads%2F8MYmfYkH9IbENnbF6iAW%2Fwhitelist.png?alt=media&#x26;token=38244d51-e762-44dd-8928-e12a4d5bfa11" alt=""><figcaption><p>Whitelisting ngrok with the wildcard subdomain</p></figcaption></figure>

{% hint style="info" %}
Make sure to save after adding the domain!
{% endhint %}

### 5. Expose your project with ngrok&#x20;

Once your project is ready to get online (any project dependencies have been configured and you are ready to test), serve it up on your local web service (localhost).

<figure><img src="https://1036686854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJPnL__mOdr_mLZ8nwf%2Fuploads%2FiCfwC9FgQ0qkzPBgn3Mc%2Fnpm_start.png?alt=media&#x26;token=77c3be27-ec7d-45d3-99dc-4365ad343cc1" alt=""><figcaption><p>npm start to get the React project onto the localhost port 3000</p></figcaption></figure>

{% hint style="info" %}
You can close the window *might* be opened in your web browser.
{% endhint %}

Now, in a separate terminal, have ngrok create a secure tunnel to make localhost accessible via the internet using the following command: `ngrok http https://localhost:<your_port_here>`. `<your_port_here>` is the port number your local web service is using.

Open the session in your browser using the forwarding address that is generated in the ngrok terminal.

<figure><img src="https://1036686854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJPnL__mOdr_mLZ8nwf%2Fuploads%2FAYrtCS6Q0DIkMtDyQM7l%2Fngrok_port.png?alt=media&#x26;token=6290597f-40df-4674-9909-38315cfde728" alt=""><figcaption><p>Open the ngrok.io Forwarding address in your browser</p></figcaption></figure>

Once you've navigated to the address in a browser, the tag at the top of the page should match the environment variable that you’ve passed in as the URL parameter in the embed code.&#x20;

In our case here, it’s “dev”.

<figure><img src="https://1036686854-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJPnL__mOdr_mLZ8nwf%2Fuploads%2Fjpgrk30jFGNjikA59x1s%2Fdev_env.png?alt=media&#x26;token=ad15419c-6adc-49c0-83da-f409ac4516eb" alt=""><figcaption><p>The "dev" environment flag</p></figcaption></figure>

{% hint style="info" %}
The forwarding address is publicly accessible on the internet, so anyone that has it will be able to test this flow. This will only stay active for as long as you have the ngrok service running in your terminal.
{% endhint %}

### ...And finally

That's it! Once you see the above page, your flow is live at the Forwarding address provided and you can start troubleshooting your page in your dev environment. &#x20;

Happy coding!&#x20;