Metadata-Version: 2.1
Name: tecoroute-proxy
Version: 0.1.0
Summary: Proxy service for easy authentication to the TecoRoute web interface.
Home-page: https://tecoroute-proxy.cze.tech/
Author: Petr Czepiec
Author-email: petr@czepiec.me
Maintainer: Petr Czepiec
Maintainer-email: petr@czepiec.me
License: MIT
Project-URL: Documentation, https://github.com/czetech/tecoroute-proxy/blob/master/README.md
Project-URL: Source, https://github.com/czetech/tecoroute-proxy
Project-URL: Tracker, https://github.com/czetech/tecoroute-proxy/issues
Project-URL: Changelog, https://github.com/czetech/tecoroute-proxy/blob/master/CHANGELOG.md
Keywords: authentication,proxy,tecoroute
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Internet :: Proxy Servers
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE

# TecoRoute Proxy

TecoRoute Proxy is a reverse proxy server that allows easy authentication to the
[TecoRoute] service using a simple POST request. It also saves the credentials and
automatically logs the user in when the TecoRoute session expires.

## How it works

The server has one control endpoint (_/tecoroute-proxy_ by default) that is used to log
in and log out of the user from the proxy. When the user logs in, all requests are
proxied to TecoRoute. The proxy session is stored only in the user's cookies, so the
server is completely stateless and no database is required.

The control endpoint accepts `POST` requests with `application/x-www-form-urlencoded`
content type (HTML form).

### Log the user in

The user logs in with the following data:

| Name       | Value                |
| ---------- | -------------------- |
| `action`   | `login`              |
| `username` | _TecoRoute username_ |
| `password` | _TecoRoute password_ |
| `plc`      | _TecoRoute plc_      |

Example of a HTML form that logs the user in:

```html
<form method="post" action="https://tecoroute-proxy.cze.tech/tecoroute-proxy">
  <button name="action" value="login">Open PLC</button>
  <input type="hidden" name="username" value="BroukPytlik" />
  <input type="hidden" name="password" value="ferda1" />
  <input type="hidden" name="plc" value="AB_1234" />
</form>
```

### Log the user out

The user logs out with the following data:

| Name     | Value    |
| -------- | -------- |
| `action` | `logout` |

Example of a HTML form that logs the user out:

```html
<form method="post" action="https://tecoroute-proxy.cze.tech/tecoroute-proxy">
  <button name="action" value="logout">Logout</button>
</form>
```

Logging out will try to log the user out from TecoRoute and delete the login data from
the user's cookies.

## Configuration

The server is configured using environment variables:

| Name                      | Description                                    | Default value               |
| ------------------------- | ---------------------------------------------- | --------------------------- |
| `TECOROUTE_PROXY_HOST`    | The host to listen on, all interfaces if empty |                             |
| `TECOROUTE_PROXY_PORT`    | The port to listen on                          | _80_                        |
| `TECOROUTE_PROXY_CONTROL` | The control path                               | _/tecoroute-proxy_          |
| `TECOROUTE_PROXY_ORIGIN`  | TecoRoute service URL                          | _https://route.tecomat.com_ |

## Usage options

TecoRoute Proxy can be used as a service, standalone application or as a Python library.

### Use as a service

Server is deployed at <https://tecoroute-proxy.cze.tech>. The control URL is:

    https://tecoroute-proxy.cze.tech/tecoroute-proxy

Feel free to use the service for testing or simple production purposes.

### Install from PyPI

Requirements:

- [Python] (version 3.6 or later)
- [pip] or another package installer for Python

Installation using pip is done with:

```shell
pip install tecoroute-proxy
```

Start the server with:

```shell
tecoroute-proxy
```

On an unprivileged port (e.g. 8080), start the server with:

```shell
TECOROUTE_PROXY_PORT=8080 tecoroute-proxy
```

It is possible to use the package as a Python library and run the server synchronously
or asynchronously in the event loop. Example of use:

```python
from tecoroute_proxy import Proxy

proxy = Proxy(port=8080)
proxy.run()
```

### Run from Docker Hub

Run the image from Docker Hub:

```shell
docker run -p 80:80 czetech/tecoroute-proxy
```

The image can be configured using [configuration](#configuration) variables.

### Install to Kubernetes using Helm

Setup Helm repository:

```shell
helm repo add czetech https://charts.cze.tech/
```

Install Helm chart:

```shell
helm install tecoroute-proxy czetech/tecoroute-proxy \
  --set ingress.enabled=true \
  --set ingress.hosts[0]=<ingress-host>
```

see the [chart] for more options.

## Source code

The source code is available at <https://github.com/czetech/tecoroute-proxy>.

[chart]: https://github.com/czetech/tecoroute-proxy/tree/main/chart
[pip]: https://pip.pypa.io/en/stable/installation/
[python]: https://www.python.org/downloads/
[tecoroute]: https://route.tecomat.com/


