{"id":20581180,"url":"https://github.com/hostconfig/https","last_synced_at":"2026-05-02T18:40:32.010Z","repository":{"id":213337469,"uuid":"733617809","full_name":"hostconfig/https","owner":"hostconfig","description":"Welcome to hostconfig/https.","archived":false,"fork":false,"pushed_at":"2023-12-27T01:51:06.000Z","size":184,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-01-16T22:37:20.179Z","etag":null,"topics":["docker","fullstack-development","https","nodejs","typescript","yarn-workspaces"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hostconfig.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2023-12-19T18:25:44.000Z","updated_at":"2023-12-24T17:42:50.000Z","dependencies_parsed_at":"2023-12-27T02:28:39.651Z","dependency_job_id":"73778ff0-cded-4f56-81d0-b096c976b5ac","html_url":"https://github.com/hostconfig/https","commit_stats":null,"previous_names":["hostconfig/https"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hostconfig%2Fhttps","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hostconfig%2Fhttps/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hostconfig%2Fhttps/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hostconfig%2Fhttps/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hostconfig","download_url":"https://codeload.github.com/hostconfig/https/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242206045,"owners_count":20089255,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","fullstack-development","https","nodejs","typescript","yarn-workspaces"],"created_at":"2024-11-16T06:27:23.902Z","updated_at":"2026-05-02T18:40:31.937Z","avatar_url":"https://github.com/hostconfig.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hostconfig/https\nWelcome to hostconfig/https.\n\nA mini express TLS-enabled https server, with out-of-the-box support for static HTML and API routes.\n\nTo start:\n\n```\nyarn build \u0026\u0026 yarn start\n```\n\n*or*\n\n```\ndocker compose up --build\n```\n\nThe ```app = express()``` object will be served at ```localhost:443``` over an http server.\n\n*NOTE:* The above may require elevated priviliges to run.\n\n## TLS-enabled\n\nGenerate a self-signed TLS certificate:\n\n```\nyarn gen:ssl\n```\n\nYou will be asked to create, and *many* times to repeat, a secure passphrase by the openSSL cli. A set of TLS certificates with certificate authority signature will be placed in a new ```.certs``` directory at the project root. If attempting to build in Docker, this directory must be present for the build to succeed (please see troubleshooting for more).\n\nThe generated output should resemble the following:\n\n```\n.certs\n└── CA\n    ├── CA.key\n    ├── CA.pem\n    └── localhost\n        ├── localhost.crt\n        ├── localhost.csr\n        ├── localhost.decrypted.key\n        ├── localhost.ext\n        └── localhost.key\ndocs\nsrc\n...\n```\n\nYou may install the provided certificate(s) on your host machine by usual means; the script will also attempt to use the ```nssdb``` library's ```certutil``` script to store a copy in the Mozilla backend storage, also used by browsers such as Chrome (at the time of writing).\n\nFor toubleshooting tips, see below.\n\n\n## Debug mode\n\nAdditionally, a debug mode can be activated:\n\n```\nyarn dbg\n```\n\n## Test mode\n\nAdditionally, a test mode can be activated:\n\n```\nyarn test\n```\n\nSee the ```test``` directory for an example.\n\n## Health check\n\nIn all three modes, a healthcheck request will be sent periodically to:\n\n```\n/health\n```\n\nSee the ```test``` directory for an example.\n\n## Troubleshooting\n\nAttempting to run Docker before generating the certificates per the instructions will likely cause the Docker build to fail, because the builder attempts to copy the certificates from your local disk (where you can use them further) instead of generating them inside of the Docker environment. A shell script named 'generate.sh' is provided which will create the required certificates in a new ```.certs/``` directory. As long as this is placed at the root of the 'https' sub-module, the Docker build should succeed. Please be vigilante about the useage of self-signed certificates; these are generally only to be used for local development purposes and should not be shared publically.\n\nEvery host (operating system) and client (browser, API) can have differing means and capabilities for managing SSL/TLS certificates and other HTTP-related settings.\n\nFor Windows and MacOS machines, one can often simply double-click on valid SSL/TLS certificates on disk, and this will launch a native installer with recommended settings based on the content of the certificate. For Linux machines (and Docker containers), the process can vary greatly. As a suggestion to begin with, typically for Ubuntu (22.04) and Alpine Linux operating systems:\n\n- Copy the generated ```localhost.crt``` file into ```/usr/local/share/ca-certificates``` (may require sudo)\n- Run ```sudo update-ca-certificates``` and the new key(s) found in the above directory will be added to the store in ```/etc/ssl``` correctly\n\n*Note that the above steps are performed inside the Docker virtual environment as part of the build script, meaning that your Docker environment will already be configured appropriately so long as it finds the required ```.certs/``` directory in the project root directory.*\n\nThe server source code in ```src/index.ts``` is already pointing at the location of the script-generated certificates - a Yarn post-build step automatically copies the certificates from the generated location to this required output location; however, this can easily be disturbed by small changes to the project without due diligence. Until a more rigourous solution presents itself, be vigilante about making sure these paths match, if you *do* make changes to the source code. In the case of invalid input being found where the TLS certificate and key are expected, an error is thrown and logged to the server; the server will proceed to run, but will not be accessible since there is no valid TLS cert or key loaded.\n\nIf the above is set up correctly, then it should be possible to verify a secure connection using openSSL at this point:\n\n```\nopenssl s_client -connect localhost:443\n```\n\nThe above command should issue and return a successful handshake, allow a connection between client and server, pass some data, and then close the connection successfully.\n\nRegarding browser support; this has been tested and is working successfully on latest Chrome, Edge, and Mozilla browsers; the typical TLS certificate installation procedure requires you to go to the usual ```settings \u003e security ``` section(s) of the configuration tab, and choose to manage your SSL/TLS/HTTP-based web security certificates. In almost all cases, one is presented with tabs for different certificate policies - usually, the browser will require you to import the ```localhost.crt``` *and* the ```CA.pem``` files, which might be supported on different tabs; the file-picker for each possible option usually reverts to looking for sensible file types that it expects, so if for example the '.pem' file does not make itself to the file-picker, try importing it under a different tab section - and if asked, choose to trust the certificate for web content.\n\n## Further reading:\n\n- NodeJs TLS/SSL documentation: [https://nodejs.org/docs/latest-v4.x/api/tls.html](https://nodejs.org/docs/latest-v4.x/api/tls.html#tls_tls_ssl)\n\n## Acknowledgments:\n\nThe ```generate.sh``` script is taken almost ad-verbatim from this excellent article from Lewel Murithi:\n\n- [https://www.section.io/engineering-education/how-to-get-ssl-https-for-localhost](https://www.section.io/engineering-education/how-to-get-ssl-https-for-localhost/)\n\nThank you Lewel!\n\nFurther tips on the content of the article/script can be found in the NodeJs documentation linked above.\n\n### Thanks for reading!\n\n[Nathan J. Hood](https://github.com/nathanjhood)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhostconfig%2Fhttps","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhostconfig%2Fhttps","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhostconfig%2Fhttps/lists"}