pcmt/README.md

pcmt

Password Compromise Monitoring Tool

🚧 note: this project is being developed as a part of my thesis and is currently a work in progress. 🚧

pcmt Gopher logo based on the Egon Elbre's awesome Gopher designs.

How to try this out

with podman and just installed, run the following:

# 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 Podman setup):

# 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 to see what's possible, or have a look at the example config.

If you're new to Dhall, its documentation page is a good resource to start at.

🔨 Building from sources

pre-requisites:

• just
• npm
• go1.20
• git

the application consists of frontend and backend. the frontend is basically a generated TailwindCSS stylesheet and it is not shipped as part of the development process. as such, it needs to be built from sources, same as the backend.

step 0: clone this repository with git

then build the frontend using just tw or just frontend

next, build the Go application using:

# debugging version.
just build

# or with debugging information stripped.
just buildrelease

alternatively, build both frontend and backend in release modes using: just prod. the order of the steps is important as the application embeds the generated stylesheet.

if you plan to run the application in LiveMode, the stylesheet can be supplied when running the application; however, the binary will lack the way to fall back to the embedded asset so bear that in mind.

if you're curious, you can open the justfile to see the details of the build targets like tw and buildrelease used above.

LICENSE

AGPL-3.0-only (see LICENSE for details).