pcmt/README.md

98 lines
3.9 KiB
Markdown

# [`pcmt`](https://git.dotya.ml/mirre-mt/pcmt/)
> Password Compromise Monitoring Tool
[![pre-commit](https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white)](https://github.com/pre-commit/pre-commit)
[![Build Status](https://drone.dotya.ml/api/badges/mirre-mt/pcmt/status.svg)](https://drone.dotya.ml/mirre-mt/pcmt)
[![Go Report Card](https://goreportcard.com/badge/git.dotya.ml/mirre-mt/pcmt)](https://goreportcard.com/report/git.dotya.ml/mirre-mt/pcmt)
[![Go Documentation](https://godocs.io/git.dotya.ml/mirre-mt/pcmt?status.svg)](https://godocs.io/git.dotya.ml/mirre-mt/pcmt)
> :construction: **note:** this project is being developed as a part of my
> [thesis](https://git.dotya.ml/mirre-mt/masters-thesis/) and is currently
> a work in progress. :construction:
<p align="center">
<figure align="center">
<img
src="https://git.dotya.ml/mirre-mt/pcmt/raw/branch/development/assets/public/img/logo-pcmt.svg"
alt="pcmt Gopher logo"
/>
<figcaption>pcmt Gopher logo based on the Egon Elbre's <a href="https://github.com/egonelbre/gophers" target="_blank">awesome Gopher designs</a>.</figcaption>
</figure>
</p>
### How to try this out
with [`podman`](https://podman.io/) and [`just`](https://github.com/casey/just)
installed, run the following:
```sh
# build the image locally using kaniko.
just kaniko
# start postgres.
just dbstart
# in another terminal, run the application.
# LiveMode=False disables loading assets and templates from the filesystem and
# instead uses the embedded resources.
podman run --rm -it -e PCMT_DBTYPE=postgres \
-e PCMT_CONNSTRING="host=127.0.0.1 port=5432 sslmode=disable dbname=postgres password=postgres"
-e PCMT_LIVE=False docker.io/immawanderer/pcmt:testbuild \
-config /etc/pcmt/config.dhall
```
while the above runs *fine*, running in **pods** is *better* and more close to
a production setting (assuming
[rootless](https://www.redhat.com/sysadmin/rootless-podman-user-namespace-modes)
[Podman](https://www.redhat.com/sysadmin/rootless-containers-podman) setup):
```sh
# create a pod 🦭.
podman pod create --userns=keep-id -p3005:3000 --name pcmt
# if you have the db from the previous example still running, terminate it by
# pressing ^C or running the following:
just dbstop
# run a db in the pod.
podman run --pod pcmt --replace -d --name "pcmt-pg" --rm \
-e POSTGRES_INITDB_ARGS="--auth-host=scram-sha-256 --auth-local=scram-sha-256" \
-e POSTGRES_PASSWORD=postgres -v $PWD/tmp/db:/var/lib/postgresql/data \
docker.io/library/postgres:15.2-alpine3.17
# run the application in the pod (assuming that you have built it as in the
# previous example). do note that we're connecting to the db using its
# container name, while localhost would also work. inside the pod, every
# container is reachable on localhost.
podman run --pod pcmt --replace --name pcmt-og -d --rm \
-e PCMT_LIVE=False \
-e PCMT_DBTYPE="postgres" \
-e PCMT_CONNSTRING="host=pcmt-pg port=5432 sslmode=disable user=postgres dbname=postgres password=postgres" \
-v $PWD/config.dhall:/config.dhall:ro \
docker.io/immawanderer/pcmt:testbuild -config /config.dhall
# also, if we try to connect to the db from the host we get an error (unless
# there is another database running on localhost already, such as the one from
# the previous example).
curl localhost:5432
--> curl: (7) Failed to connect to localhost port 5432 after 0 ms: Couldn't connect to server
# that is because the database port has not been exposed from the pod (recall
# the pod creation command).
```
#### Custom config
Make sure to check out the Dhall configuration
[schema](https://git.dotya.ml/mirre-mt/pcmt-config-schema/src/branch/development/schema.dhall)
to see what's possible, or have a look at the [example
config](exampleConfig.dhall).
If you're new to Dhall, its [documentation](https://docs.dhall-lang.org/) page
is a good resource to start at.
### LICENSE
AGPL-3.0-only (see [LICENSE](LICENSE) for details).