Table of Contents
Shortcuts

Devlove mode

Develop with HTTP/2 and HTTPS

Developing websites with HTTPS+HTTP/2 is harder than just using plain old HTTP. For one, there are more things to configure: domain names, matching certificates and encryption. For another, an HTTP/2 socket is encrypted and may be used to transfer several files simultaneously, which is good but makes harder to troubleshoot issues. Last but not least, to reap the performance benefits of HTTP/2 one needs to take into account latency, HTTP/2 priorities and HTTP/2 Push during development, not as an after-thought.

We try to make all of that very easy or automatic. We also think that if one person in a team creates a setup for a website, the other members of the team should only need to clone a repository to be up and going.

For a web server, there are situations when one must decide between being helpful to people creating websites, or having more security and performance goodies. In ShimmerCat, we decide in favor of developers in the devlove operation mode, while with internet mode we decide for the later.

How to use devlove mode

We already saw a very simple example in our Get Started guide where ShimmerCat was used in devlove mode. If you have not seen that guide, do that now, the entire guide fits in a screen and it takes five minutes to complete. Here we will just describe the more practical aspects.

Running devlove

As we saw before, running devlove is easy. Here are the very basic steps:

  • In a terminal, change to the directory where your project is.

  • If you are just starting your project, edit your devlove.yaml file according to your needs. You can use the devlove.yaml file in the Get Started guide as a starting point. If you need something more advanced (like talking to a backend application or serving several domains), take a look to our Structuring Apps guide.

  • Run shimmercat devlove

ShimmerCat will start running in the foreground, and you should be able to see your site. If this is the first time even that you use ShimmerCat, you will need to setup a browser for ShimmerCat. We will get to that in a minute, but just let me write below the other things that you should know when using ShimmerCat:

  • To terminate ShimmerCat, press Ctrl+C.

  • If you are using SOCKS5 and your site loads resources from third party services, use the -w option.

HTTPS setup for development

ShimmerCat sets up certificates for the domains you configure in the devlove.yaml file automatically. For example, for the devlove.yaml file in our Get Started guide, ShimmerCat will generate a certificate for the domain www.hello.com. The certificate itself is stored on the project directory where you run ShimmerCat, inside ShimmerCat’s scratch folder.

Those are development certificates, and they are signed with a CA certificate which is also generated for you. The CA is stored at ~/.config/mousebox/ so that it can be re-used for all your development projects. The only quirk is that you need to configure a browser to trust this CA certificate. We recommend to do this in a special development profile.

Creating a development profile for Chrome can be done automatically with the sc-tool, but if you want to do it by hand here are some links to help you:

We have a built-in SOCKS5 server that presents your website as part of a network “imagined” by ShimmerCat (this video explains it better). We like to configure our development browser to use this SOCKS5 proxy. In this way we can connect to our in-development website using just its name but without needing to change /etc/hosts. The sc-tool also configures SOCKS5 in Chrome’s development profile when invoked as sc-tool chrome.

The manual procedure for making browsers trust your CA is explained below.

Installing the development CA certificate for browsers in Linux

Google Chrome

Navigate to chrome://settings, click “Show advanced settings…” at the bottom, and then scroll to HTTPS/SSL and click the “Manage certificates” button. In the dialog that appears, select the “Authorities” tab and click the “Import…” button, then browse to the file with name “mousebox_ca_root_xxxxxx” in your Mousebox’s config directory, i.e. ~/.config/mousebox. In the dialog that appears, instruct the browser to trust this certificate for identifying websites.

Mozilla Firefox

Navigate to “about:preferences” , then select “Advanced” in the right bar, and then click in the “Certificates” tab. Click the “View Certificates” button, and select the “Authorities” tab. Click the “Import…” button, then browse to the file with name “mousebox_ca_root_xxxxxx” in your Mousebox’s config directory, i.e. ~/.config/mousebox. In the dialog that appears, instruct the browser to trust this certificate for identifying websites.

Installing the development CA certificate for Mac OS X

Mac OS X users need to use the Keyring Manager to install the CA certificate. The certificate itself can be found at the ~/.config/mousebox folder. You can do it manually, or you can use sc-tool. Install it with pip install sc-tool and execute:

sc-tool add-ca

Miscellaneous characteristics of devlove mode

These are some details that you may find useful:

  • SOCKS5 proxy is open by default at port 2006.

  • In devlove mode, and only in devlove mode, ShimmerCat adds a header sc-view to responses forwarded from an inner application indicating the SC-view that rendered it.

  • Only one ShimmerCat process is launched.

Handling of error status codes

When the application backend returns a 404 code for an electric domain, ShimmerCat relays that 404 answer to the client. This behavior is exclusive to devlove mode. In Internet mode, ShimmerCat looks instead for a generic __404.html template.

In devlove mode, ShimmerCat will also relay responses with 500 status codes literally to the browser, but they will be replaced by a generic terse message in Internet mode. The intention is to avoid leaks of sensitive information that may be present in 500-error application diagnostics from production servers.