Local Development

section.io’s local development is designed to allow you to develop and test changes to your content delivery configuration without having to work in production or spin up another copy of the production environment to test on. This is done by replicating the production delivery environment in a virtual machine (VM) running on your computer. In this VM you can change the configuration of the proxies setup to deliver your site and see what works best before actually putting it in front of your website.

section.io’s local development environment is based on git, Vagrant and VirtualBox. Please ensure you have the latest version of these installed before progressing.

The command line interface

To make working with the local development virtual machine easier, section.io provides a command line interface (CLI) to interact with the VM and deploy changes. To get started, download the CLI by git cloning https://github.com/section-io/section.cli. At the command prompt where you cloned the CLI you need to run section up <token>. You need to replace <token> with the token shown when you switch to the Development environment in https://aperture.section.io for your site.


This will download the VM and get it running with your application. The section.io CLI is a very useful tool, but at the end of the day it is merely a convenient wrapper around vagrant and git. To learn all the CLI can do, read the command line documentation.

Once the section up command finishes you will have a Vagrant virtual machine running a copy of the same reverse proxies that are in our hosted Production environment. The CLI clones a copy of your git repository under the apps folder. So if you have setup www.shop.com on section.io you will now have an www.shop.com folder in there. This contains your git repository that controls section.io. By default if has checked out the Production branch. This is the default environment created when you signed up. When you push changes to the Production branch it will be automatically deployed out to the actual hosted environment, so make sure you test your changes locally.

Other than the fact that the default branch is Production rather than master, this is a normal git repo. You can make your own branches, commit changes to them and push those branches up so that other people in your team can colaborate on the development. Updates to the hosted environment will only happen once you merge your changes into the Production branch and push to origin.

Accessing your application through Section

Once you have provisioned your local instance of Section with the cli you can route local access to your application through the local proxy stack.

The simplest solution is to modify your local HOSTS file. On Windows the HOSTS file typically found at c:\windows\system32\drivers\etc\hosts and on Mac OS X typically at /private/etc/hosts. On both platforms you will require elevated privileges to edit the file.

You need to add an entry to the HOSTS file specifying the IP address of your local Section instance and the domain name of your web application. The default IP address for a local Section instance is and, for example, your application domain name might be www.shop.com. The line you add to your HOSTS file will look similar to this:   www.shop.com

After saving the changes to the HOSTS file, you may need to force your web browser to flush its DNS cache, eg by restarting it.

Now, when you browse to http://www.shop.com/ in your web browser, the requests will first go to the local Section proxy stack and then to the origin address configured for your Section environment.

Alternative to the HOSTS file

If editing the HOSTS file is not feasible, or not preferred, you may try tools like Telerik Fiddler on Windows or Charles on Windows and Mac OS. Both of these tools allow HOSTS file overrides (aka DNS spoofing).

Performing requests through Section from command-line tools

Command line tools like cURL and PowerShell’s Invoke-WebRequest will allow you to specify the IP address to use to establish the connection while specifying a different value to pass via the Host HTTP request header.

Example with cURL:

curl -H 'Host: www.shop.com'

Example with PowerShell:

Invoke-WebRequest -Headers @{ Host='www.shop.com' }

Removing DNS override and restoring normal access to your application

If you need to remove the local Section proxy stack from being involved in your local access to your web application, either temporarily, or permanently, just undo your changes from above.

That is, remove the line you added to your HOSTS file, or prefix the line with # if you plan to re-enable Section later, eg:

#   www.shop.com

Remember, you may need to restart your web browser.

If you opted to use Fiddler, Charles or similar, remove the HOSTS override configuration, or turn off the Capture Traffic option.

Using a different host header for local development

If you prefer to use a different host header to do local development, eg dev.shop.com, you can configure this. By defualt when we setup your reverse proxy stack, the edge proxy will only respond to the host header you first signed up with. You can override this for local development by putting a local.config.json file in the root of your repository (found under the apps folder where you ran section up) containing this:

  "edge": {
    "host_headers": ["dev.shop.com"]

Now run section reload where you cloned the CLI. You can update your hosts file to point at dev.shop.com rather than www.shop.com.

Switching between applications

You can have multiple applications checked out to your local development environment that you may want to switch between. This is especially important if you have split applications. CLI commands like push, promote and reload operate on the currently active application. By default the active application is the last one you ran section up for, but you can quickly switch between them by running section init <token>, replacing <token> with the development token for the application you want to switch to.