Development and Contributing

Pinchflat is written in Elixir - a functional programming language that runs on the Erlang VM. It uses the Phoenix web framework and SQLite for the database. The frontend is mostly normal server-rendered HTML with a little Alpine.js as-needed.

Elixir is a personal favourite of mine and is ideal for building fault-tolerant systems. It's also a joy to work with and has a great community. If you're interested in contributing, I'd be happy to help you get started with Elixir - just open an issue with some questions and we can chat!

Local setup

VSCode (fastest and easiest method)

VSCode users can use devcontainers to automatically set up a development environment inside a Docker container. This saves you from having to figure out extensions, install any package managers, stuff like that. For an obscure language like Elixir this takes all the hassle out of getting started!

• Simply click here
• Give it a few minutes while it builds for the first time

or

• Install the Dev Containers extension
• Clone the repo and open it in VSCode
• Accept when it prompts you to "Reopen in Container"
• Give it a few minutes while it builds for the first time

When using either of these methods I recommend opening at least two panes in your terminal. One should run the command docker attach pinchflat-phx-1 to see logs and interact with the Elixir REPL. The other should run docker compose exec phx zsh for things like running tests. See the "running tests and linting" section below for more.

Traditional install

• Navigate to the Pinchflat project directory
• docker compose build --no-cache
• docker compose up -d && docker attach pinchflat-phx-1
• After a few minutes the app should be accessible at localhost:4008
  • Please let me know if you run into any hiccups here - I haven't had to bootstrap the app from scratch in a long time and I might have forgotten something
• Media downloads and config will be stored in the tmp directory. Not the OS's /tmp directory, but the one in the root of the project

Running tests and linting

• Open a shell with docker compose exec phx zsh
• Run mix test to run the tests
• Run mix check to do a full testing, linting, and static analysis pass

NOTE: I've put as many tooling config files as possible in the tooling/ directory. The CLI commands above will Just Work™, but you may have to tell any editor tooling to look in that directory for its config files.

Top tips

• Look for any module that ends in *_worker.ex - these are where the interesting stuff happens and you can trace back from there to see how the app works. lib/pinchflat/slow_indexing/media_collection_indexing_worker.ex is a good place to start
• There is a database ERD that's stored at priv/repo/erd.png