Home

Awesome

CI Project Status: Concept – Minimal or no implementation has been done yet, or the repository is only intended to be a limited example, demo, or proof-of-concept. Community Support

NJS + ACME = Certs!

njs-acme

This repository provides a JavaScript library to work with ACME providers such as Let's Encrypt for NJS. The source code is compatible with the ngx_http_js_module runtime. This allows for the automatic generation and renewal of TLS/SSL certificates for NGINX.

Requires at least njs-0.8.2, which is included with NGINX since nginx-1.25.3.

NOTE: Some ACME providers have strict rate limits. Please consult with your provider. For Let's Encrypt refer to their rate-limits documentation.

Installation

There are a few ways of using this repo. You can:

Each option above is detailed in each section below.

Downloading the Latest Release

You can download the latest released acme.js file from the Releases page. Typically you would place this in the path /usr/lib/nginx/njs_modules/acme.js in your NGINX server. See the example nginx.conf to see how to integrate it into your NGINX configuration.

To integrate the downloaded acme.js file into a Docker image, you can add the following to your Dockerfile:

RUN mkdir -p /usr/lib/nginx/njs_modules/
RUN curl -L -o /usr/lib/nginx/njs_modules/acme.js https://github.com/nginx/njs-acme/releases/download/v1.0.0/acme.js

Creating a Docker Image

To create an Nginx+NJS+njs-acme Docker image, simply run:

% make docker-build
...
 => exporting to image
 => => exporting layers
 => => writing image ...
 => => naming to docker.io/nginx/nginx-njs-acme

This will build an image with a recent version of NGINX, required njs version, and the acme.js file installed at /usr/lib/nginx/njs_modules/.

The image will be tagged nginx/nginx-njs-acme, where you can use it in place of a standard nginx image.

When running the container, we advise mounting the /etc/nginx/njs-acme/ directory in a Docker volume so that the cert/key are retained between deployments of your nginx container. The docker-compose.yml file in this directory shows an example of doing this using the certs volume.

Building acme.js With Docker

If you want to use your own NGINX installation and do not want to have to worry about installing Node.js and other build dependencies, then you can run this command:

make docker-copy

This will build the full image and copy the acme.js file to the local dist/ directory. You can then include this file in your NGINX deployments.

Building acme.js Without Docker

If you have Node.js and NPM installed on your computer, you can run this command to generate acme.js directly:

make build

This will generate dist/acme.js, where you can then integrate it into your existing NGINX / NJS environment.

Configuration Variables

You can use environment variables or NGINX js_var directives to control the behavior of the njs-acme.

In the case where both are defined, environment variables take precedence. Environment variables are in ALL_CAPS, whereas the nginx config variable is the same name, just prefixed with a dollar sign and $lower_case.

For example, NJS_ACME_SERVER_NAMES (env var) is the same as $njs_acme_server_names (js_var).

Staging by Default

The value of the variable NJS_ACME_DIRECTORY_URI (js_var $njs_acme_directory_uri) defaults to Let's Encrypt's Staging environment. When you are finished testing with their staging environment, you will need to define/change the value of this to your ACME provider's production environment. In Let's Encrypt's case the production URL is https://acme-v02.api.letsencrypt.org/directory.

You will need to remove the staging certificate from your NGINX server's filesystem when changing from staging to production. It is located in /etc/nginx/njs-acme/ by default (controlled by the variable NJS_ACME_DIR).

Required Variables

Optional Variables

NGINX Configuration

There are a few pieces that are required to be present in your nginx.conf file. The file at examples/nginx.conf shows them all.

NOTE: The examples here use js_var for configuration variables, but keep in mind you can use the equivalent environment variables instead if that works better in your environment. See the Configuration Variables section above for specifics.

nginx.conf Root

http Section

server Section(s)

location Blocks

Development

This project uses Babel and Rollup to compile TypeScript sources into a single JavaScript file for njs. It uses Mocha with nginx-testing for running integration tests against the NGINX server. This project uses njs-typescript-starter to write NJS modules and integration tests in TypeScript.

The ACME RESTful client is implemented using ngx.fetch, crypto API, PKI.js APIs in the NJS runtime.

With Docker

There is a docker-compose.yml file in the project root directory that brings up an ACME server, a challenge server, a Node.js container for rebuilding the acme.js file when source files change, and an NGINX container. The built acme.js file is shared between the Node.js and NGINX containers. The NGINX container will reload when the acme.js file changes.

VSCode Devcontainer

If you use VSCode or another devcontainer-compatible editor, then run the following:

code .

Choose to "Reopen in container" and the services specified in the docker-compose.yml file will start. Editing and saving source files will trigger a rebuild of the acme.js file, and NGINX will reload its configuration.

Docker Compose

If you just want to start the development environment using Docker (no devcontainer) then run:

make docker-devup

Without Docker

To follow these steps, you will need to have Node.js version 14.15 or greater installed on your system.

  1. Install dependencies:

    npm ci
    
  2. Start the watcher:

    npm run watch
    
  3. Edit the source files. When you save a change, the watcher will rebuild ./dist/acme.js or display errors.

Testing

With Docker

  1. Start a test environment in Docker:

    make docker-devup
    
  2. Optionally you can watch for nginx log file in a separate shell:

    docker compose logs -f nginx
    
  3. When started initially, nginx will not have certificates at all. If you use the example config, you will need to wait one minute for the js_periodic directive to invoke acme.clientAutoMode to create the certificate.

  4. Send an HTTP request to nginx running in Docker:

    curl -vik --resolve proxy.nginx.com:8000:127.0.0.1 http://proxy.nginx.com:8000/
    
  5. Send an HTTPS request to nginx running in Docker to test a new certificate:

    curl -vik --resolve proxy.nginx.com:4443:127.0.0.1 https://proxy.nginx.com:4443
    
  6. Test with openssl:

    openssl s_client -servername proxy.nginx.com -connect localhost:4443 -showcerts
    
  7. Display content of certificates

    docker compose exec -it nginx ls -la /etc/nginx/njs-acme/
    

The docker-compose file uses volumes to persist artifacts (account keys, certificate, keys). Additionally, letsencrypt/pebble is used for testing in Docker, so you don't need to open up port 80 for challenge validation.

Build Your Own Flows

If the reference implementation does not meet your needs, then you can build your own flows using this project as a library of convenience functions.

Look at clientAutoMode in src/index.ts to see how you can use the convenience functions to build a ACME client implementation. There are some additional methods in src/examples.ts showing how to use the ACME account creation APIs or generating Certificate Signing Requests on demand.

Project Structure

PathDescription
srcContains your source code that will be compiled to the dist/ directory.
integration-testsIntegration tests.
unit-testsUnit tests for code in src/.

Contributing

Please see the contributing guide for guidelines on how to best contribute to this project.

License

Apache License, Version 2.0

© F5, Inc. 2023