= Testing SSL in localhost

In some cases is useful to access the `localhost` environment under SSL (ie: `https://localhost:3443/`).

A typical use case is when you want to test login integration with 3rd party systems using OAuth (which in the latest versions only the HTTPS protocol is allowed).

Using Puma, the default server for Rails, you can easily do the trick by creating a self-signed certificate and using it when starting your development environment. A dummy certificate is shipped within the `decidim-dev` module which is usually included in the `:development` group of your `Gemfile`.

== Starting development in SSL mode

If you created the Decidim development app using the default development app generator, you already should have the necessary configurations for starting the development server under SSL. You can start the development server under SSL at port 3443 (default) using the following command:

[source,bash]
----
DEV_SSL=true bin/rails s
----

Also make sure that the `decidim-dev` gem is included in the `:development` group of your `Gemfile` as it should be unless you changed it.

After that, you can start the development server under SSL at port 3443 (default) using the following command:

Now you are ready to visit your favorite browser at the address `https://localhost:3443/` (note "https" and port 3443). If you would like to test the non-SSL "http" version, it is also running normally at port 3000, so you can access that as you normally would.

Note: Your browser is going to complain as this is a self-signed certificate, that is ok for development, just add an exception and accept the certificate.

== Testing tenants using lvh.me

You can also test the multi-tenant capabilities of Decidim by using alternative domains or subdomains that points to your local machine. `lvh.me` is a service that does just that without configuring anything in your machine (an alternative is to add entries in your `/etc/hosts` with a testing domain of your choice). Just point your browser to any subdomain of `lvh.me` and you will be in your own machine.

Just access your `/system` admin and create new organization with some subdomain of `lvh.me`: `organization.lvh.me`, `tenant2.lvh.me`, etc.

You can combine this with the previously generated certificate (your browser is going to complaint but just tell it to proceed vising the site).

Finally remember to add the port as `lvh.me` do not forwards anything, for instance (use `http` or `https` depending on how you have started Rails):

`http://someorg.lvh.me:3000/`

`https://someorg.lvh.me:3000/`

`http://anotherorg.lvh.me:3000/`

`https://anotherorg.lvh.me:3000/`

etc.

== Optional: Create your own self-signed certificate for localhost

If you do not want to rely on the dummy certificate shipped with the `decidim-dev` gem, you can also create the certificates yourself.

First you need a SSL certificate for the `localhost` domain (you only need to execute this command once):

[source,bash]
----
openssl req -x509 -out localhost.crt -keyout localhost.key \
  -newkey rsa:2048 -nodes -sha256 \
  -subj '/CN=localhost' -extensions EXT -config <( \
   printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")
----

This will generate two files: `localhost.crt` and `localhost.key`, you can store them anywhere you want to use them later. In this example we will suppose we have them in the folder `certs` in our root user home:

[source,bash]
----
mkdir ~/certs/
mv localhost.crt ~/certs/
mv localhost.key ~/certs/
----

== Optional: Manually starting development server in SSL mode

Once you have your certificate is generated, just use the next command in order to start puma instead of the typical `bin/rails s`:

[source,bash]
----
bin/rails s -b "ssl://127.0.0.1:3443?key=$HOME/certs/localhost.key&cert=$HOME/certs/localhost.crt"
----

Now you are ready to visit your favorite browser at the address `https://localhost:3443/` (note "https" and port 3443).

Take into account that starting Puma in SSL mode manually will disable accessing it in non-ssl mode (normal `http` protocol).