Skip to content

Latest commit

 

History

History
277 lines (189 loc) · 8.78 KB

Readme.md

File metadata and controls

277 lines (189 loc) · 8.78 KB
Raw

Local SSL Management

This project is the iteration of https://github.com/dimaslz/local-ssl-management-docker, to do the same but throuth a UI or CLI (currently the only option).

This CLI is to manage local SSL certifications by mkcert. The key of this script: do not use ports in the domain and use all of them through port 443.

The solution is simple, it is running a Nginx container as reverse proxy.

Example:

https://local.your-domain.tld:3000 → https://local.your-domain.tld

ℹ️ At the moment, just tested in MacOS

From version 1.0.0, also is possible to setup a reverse proxy for microservices on the same domain.

Example:

Request to https://local.your-domain.tld/ will serve http://localhost:3000

Request to https://local.your-domain.tld/app-name will serve http://localhost:4000

Content

Install cli

npm install -g @dimaslz/local-ssl-management-cli

https://www.npmjs.com/package/@dimaslz/local-ssl-management-cli

Then the CLI will be

$ local-ssl
Usage: local-ssl [options] [command]

Options:
  -h, --help                    display help for command

Commands:
  create [options] <domain>     Create domain
  list                          List domains
  update [options] <domain|id>  update domain
  remove [options] <domain|id>  Remove domain
  reset                         Remove all domain in `/etc/hosts` created by this cli
  help [command]                display help for command

Commands

By default, the CLI will ask to your system password to be able to updathe the /etc/hosts file. If you skip it, keep in mind that you need to update it manually.

[...]
#--------------- LOCAL SSL ---------------#
your-domain.com           127.0.0.1
#--------------- LOCAL SSL ---------------#

always at the end of the file

create domain config

$ local-ssl create local.your-name.com --location / --port 3000

Now, go to your favourite browser and visit https://local.your-name.com and should be serving what is serving on http://localhost:3000.

create new location for a existing domain

$ local-ssl create local.your-name.com --location /app --port 4000

rename location

$ local-ssl update local.your-name.com --location /app,/new-app

Also you can update the port at the same time if you want.

update port to a location

$ local-ssl update local.your-name.com --location /new-app --port 4000

update location and port

$ local-ssl update local.your-name.com --location /,/new-app --port 4000

Now, intead of access to https://local.your-domain.com/app, you should access to https://local.your-domain.com/new-app

remove domain

$ local-ssl remove local.your-domain.com

remove location for a domain

$ local-ssl remove local.your-domain.com --location /new-app

list current service configs

$ local-ssl list

reset hosts

$ local-ssl reset

Use case

Sometimes we need to use HTTPS for some security restrictions or just to work closely to the PRODUCTION reality.

This is not a common use case, just it is a particular scenario on my side. Probably you do not need this to work with multiple projects in local but, it is helpful for me, also maybe for you.

Some of projects I work, has a authentication process linked to some platform like Github for example. Following this case, to setup your authentication process, you need to give a callback url like https://local.your-domain.com:3000, but sometimes I need to change the PORT for some reason. The problem is, I need to change the PORT in the service where I doing the authentication process and, all the parts in the code where I have the domain set, as for example, in the environment vars.

Now, you can work without port when you use HTTPS, so, you can access to https://local.your-domain.com directly, without specify the PORT. With this CLI, back to the Github authentication case, just you need to give the domain, without care when you change the PORT.

Yes, this is a specific use case but for me, sometimes is very useful and, I do not need to touch anything on my machine.

Other use cases

  • When you need to do something related with different TLD, as for example: setup a default language according to the TLD. You do not need to add a special script to get the TLD.
  • ...

Requirements

  • Nodejs +16
  • Docker
  • Mkcert
  • Update /etc/hosts manually

How it works?

Local SSL Management - Project idea

Basically, the script creates a container based on nginx, and this container works as reverse proxy for local domains, like in a server.

How to use

By default, always is created the certifications for https://localhost

#1 - Update your /etchosts:

MacOS and Linux:

Do it manually or the script will do it.

...
#--------------- LOCAL SSL ---------------#
127.0.0.1     local.your-domain.com
#--------------- LOCAL SSL ---------------#

#2 - Create new domain:

$ local-ssl create local.your-domain.com --location / --port 4200

or for multiple domains...

$ local-ssl create local.your-domain.com,local.your-domain.es --location / --port 4200

List domain to check it

Local SSL Management - list domains configured

The script will:

  • Store the configs.
  • Create the nginx.conf per each domain.
  • Create or update the Dockerfile configuration.
  • Remove and create the new image (named local-ssl-management).
  • Remove and create the new container (named local-ssl-management).

#3 - Run your application:

The script will work but, if your application is not running, the domain with not resolve the source.

#4 - Go to your domain and check it:

Go you your application local domain: https://local.your-domain.com and... should work 😅.

For sure, if the service is not working, the result will response a server error.

TODO

  • Serve dashboard on https://localhost
    • Manage domains by UI
    • Show logs in a friendly ui
    • Allow edit Nginx config
  • Add certs manually
  • Add custom nginx config
  • Test on Windows
  • Allow do not use HTTPS

Packages

app

UI of the project (WIP)

cli

Command line to manage local SSL certificates. (all information on this readme)

core

Common methods and functions to use in app and cli. At the moment not very useful because the app is not ready.

landing page

Landing page to present the project. (coming soon...)

Author

{
  "name": "Dimas López Zurita",
  "role": "Senior Software Engineer",
  "alias": "dimaslz",
  "linkedin": "https://www.linkedin.com/in/dimaslopezzurita",
  "github": "https://github.com/dimaslz",
  "twitter": "https://twitter.com/dimaslz",
  "tags": "tooling, docker, tailwindcss, vue, SAAS, nodejs+express"
}

My other projects