= Password change
Jakub Jirutka <https://github.com/jirutka[@jirutka]>
//custom
:proj-name: change-password
:gh-name: jirutka/{proj-name}
:wikip-url: https://en.wikipedia.org/wiki
:pypi-url: https://pypi.python.org/pypi

The aim of this project is to provide a very simple web form for users to be able to change their password stored in LDAP or Active Directory (Samba 4 AD).
It’s built with http://bottlepy.org[Bottle], a WSGI micro web-framework for Python.


== Installation

Clone this repository and install dependencies:

[source, sh, subs="+attributes"]
----
git clone [email protected]:{gh-name}.git
cd {proj-name}
pip install -r requirements.txt
----

=== Requirements

* Python 3.x
* {pypi-url}/bottle/[bottle]
* {pypi-url}/ldap3[ldap3] 2.x


== Configuration

Configuration is read from the file link:settings.ini.example[settings.ini].
You may change location of the settings file using the environment variable `CONF_FILE`.

If you have Active Directory (or Samba 4 AD), then you *must* use encrypted connection (i.e. LDAPS or StartSSL) – AD doesn’t allow changing password via unencrypted connection.


== Run it

There are multiple ways how to run it:

* with the built-in default WSGI server based on https://docs.python.org/3/library/wsgiref.html#module-wsgiref.simple_server[wsgiref],
* under a {wikip-url}/Web_Server_Gateway_Interface[WSGI] server like https://uwsgi-docs.readthedocs.org[uWSGI], http://gunicorn.org[Gunicorn], {pypi-url}/mod_wsgi[mod_wsgi], … (recommended)
* as a {wikip-url}/Common_Gateway_Interface[CGI] script.

=== Run with the built-in server

Simply execute the `app.py`:

[source, python]
python3 app.py

Then you can access the app on http://localhost:8080.
The port and host may be changed in link:settings.ini.example[settings.ini].

=== Run with uWSGI and nginx

If you have many micro-apps like this, it’s IMO kinda overkill to run each in a separate uWSGI process, isn’t it?
It’s not so well known, but uWSGI allows to “mount” multiple application in a single uWSGI process and with a single socket.

[source, ini, subs="+attributes"]
.Sample uWSGI configuration:
----
[uwsgi]
plugins = python3
socket = /run/uwsgi/main.sock
chdir = /var/www/scripts
logger = file:/var/log/uwsgi/main.log
processes = 1
threads = 2
# map URI paths to applications
mount = /admin/{proj-name}={proj-name}/app.py
#mount = /admin/change-world=change-world/app.py
manage-script-name = true
----

[source, nginx]
.Sample nginx configuration as a reverse proxy in front of uWSGI:
----
server {
    listen 443 ssl;
    server_name example.org;

    ssl_certificate     /etc/ssl/nginx/nginx.crt;
    ssl_certificate_key /etc/ssl/nginx/nginx.key;

    # uWSGI scripts
    location /admin/ {
        uwsgi_pass  unix:/run/uwsgi/main.sock;
        include     uwsgi_params;
    }
}
----

== Screenshot

image::doc/screenshot.png[]


== License

This project is licensed under http://opensource.org/licenses/MIT/[MIT License].
For the full text of the license, see the link:LICENSE[LICENSE] file.