Localhost & CORS

This page describes the process of creating entries in your local /etc/hosts file, so you can use full domain names when using a form.io portal running on localhost.

This will NOT allow just anyone on the internet to enter the domain name, and access the portal running on your machine. There's a lot of routing and DNS work needed to make that happen.

Set up your hosts file

You need superuser / administrator access to your device to do this


On macs/linux, that file is /etc/hosts. Windows works similarly, but please consult Google for specific differences. This should mostly apply still.

Inside of the file, you should see text that looks like this: localhost

This says "the domain localhost should ALWAYS resolve to". We want to add to this list for the form.io in a development scenario.

Make sure your domains end in .local localhost portal.form.io.local formio.form.io.local api.form.io.local form.io.local

This sets up the minimum domains needed to have portal.form.io.local re-reroute to an instance of the form.io portal running locally, and not immediately catch fire.

If an https connection is required for their testing, letsencrypt can be used to generate self signed certificates for this use case. However, the portal does not accept connections on port 443, so a reverse proxy will be required as part of that.

Set up the container

Here is an example set of environment variables that can be passed into the container to utilize this routing:

# - PROTOCOL=https
- DOMAIN=form.io.local

If you have https certificates, include PROTOCOL, otherwise it can be omitted. The container should be attached to port 80 on the local machine.

Now, the routing is set up, and the portal is expecting requests from that domain. You should be able to load "portal.form.io.local" in your browser, and your computer should re-route the request to the formio/enterprise container running on your localhost.

Because you are using full domains now, CORS should respond the same way that it does in production.

Project URLS

Watch out for subdomain projects urls. Those will need to also be added to the hosts file as they are created.

  • {project_id}.form.io.local

  • Ex: fxpxblopaprmpef.form.io.local

Alternately, if you are feeling brave, you can use dnsmasq to take advantage of wildcards. That's beyond the scope of this page (related reading)