Contributing

Instructions for contributors

In order to make a clone of the Github repo:

$ git clone https://github.com/caltechads/nginx-ldap-auth-service.git

Workflow is pretty straightforward:

  1. Make sure you are reading the latest version of this document.

  2. Setup your machine with the required development environment

  3. Checkout a new branch, named for yourself and a summary of what you’re trying to accomplish.

  4. Make a change

  5. Make sure all tests passed

  6. Commit changes to your branch

  7. Merge your changes into master and push.

Preconditions for working on nginx-ldap-auth-service

You’ll need Python 3.11.3 installed. We recommend using pyenv to manage your Python installations. You’ll also need pip and wheel installed.

$ cd nginx-ldap-auth-service
$ pyenv virtualenv 3.11.3 nginx-ldap-auth-service
$ pip install --upgrade pip wheel
$ pyenv local nginx-ldap-auth-service

After that please install libraries required for development:

$ pip install -r requirements.dev.txt

Precondiions for running the docker-compose stack in development

Since nginx-ldap-auth-service authenticates against an LDAP or Active Directory service, you will need to provide one. The LDAP/AD server you use needs these features:

  • It must support STARTTLS

  • It must support LDAPv3

  • It must support SIMPLE bind

  • It must have an account that with sufficient privileges to bind to the LDAP/AD server with a password and search for users.

Prepare the docker environment

Now copy in the Docker environment file to the appropriate place on your dev box:

$ cp etc/environment.txt .env

Edit .env replace these with settings appropriate for your LDAP/AD server:

  • __LDAP_URI__

  • __LDAP_BINDDN__

  • __LDAP_BASEDN__

  • __LDAP_PASSWORD__

Build the Docker image

$ make build

Run the stack

$ make dev

This will bring up the full dev stack:

  • nginx

  • nginx-ldap-auth-service

If you want to bring up a redis instance for session storage, you can do that by uncommenting the redis service in docker-compose.yml and adding these two settings to the environment section of the nginx_ldap_auth_service service:

- SESSION_BACKEND=redis
- REDIS_URL=redis://redis:6379/0

Use your dev environment

You should how be able to browse to https://localhost:8443/ and be redirected to the login page.