ExFinance

Finance applications written in Elixir

Development

Requirements

The finance app needs the elixir language to be installed. You can install it manually or via the asdf package manager, using the fixed version from the .tool-versions files

• Ubuntu/Debian SO
• asdf latest
• Elixir 1.14.3
• Erlang 25.2.1
• Node 16.13.1
• Docker 24.0.2 (optional): used to run dockerized images of the backend

Elixir, Erlang and Node can also be installed using asdf. Personal installation notes.

asdf plugin-update --all
asdf plugin-add erlang
asdf plugin-add elixir
asdf plugin-add nodejs
asdf install

Versions inside .tool-versions will be installed.

Recommended Editors and Extensions

• VSCodium, free alternative for VSCode.
• VSCode
• ElixirLS brings debugging, static analysis, formatting and code highlight support.
• Elixir Linter (Credo) suggests code formatting, refactoring oportunities and promotes code consistency.
• ESLint provides code consistency and beso practices for Javascript.
• markdownlint brings consistency for writing documentation using markdown.

NOTE: this tool help us detect issues that are eventually checked via git hooks or CI.

Git hooks

This project uses elixir_git_hooks t prevent common issues during the CI.

Git hooks implementation can be found in config/dev.exs.

This hooks are automatically installed when the project compiles: mix compile. They can also be manually installed or run from a terminal:

• Installation: mix git_hooks.install
• Run a specific hook: mix git_hooks.run pre_commit
• Run all hooks: mix git_hooks.run all

Environment variables

Copy .env.example to the project root and rename it .env. Then assign the following values:

cp .env.example .env

App

• PHX_HOST: a hsot IP. Example: 127.0.0.1 (local), 192.168.0.xxx (lan), 0.0.0.0 (lan). This is mostly using in staging or production environments.

Database

• DB_USERNAME: username for a root user in the development postgres database.
• DB_PASSWORD: password for a root user in the development postgres database.

Mailing Service

• SENDGRID_API_KEY: Sendgrid API key.

Stock price service

• FINNHUB_API_KEY: The Finnhub API key.

Cafecito username

• CAFECITO_USERNAME: The Cafecito app username.

The assigned directory for uploads

• UPLOADS_PATH: the assigned path for uploads.

Useful commands

This project uses Makefile to interact with the Elixir server, the postgres service, database and a variety of mix tools.

Displays helpful information about each command.

make help
# Shortcut
make

Configuration commands

Installs a complete development environment. This is useful when changing branches or testing PRs with new dependencies.

make setup

Installs dependencies only.

make setup.deps

Simulates a complete envrionment re-installation. This is useful when stepping into client or server dependencies conflicts, migration issues or PR revisions that are not backwards compatible to current versions.

make reset

Convenience for dropping the development database only.

make reset.ecto

Convenience for dropping the testing database only.

make reset.ecto.test

Server commands

Starts an Elixir server with an interactive shell sesion.

make server

Testing commands

Runs all tests.

make test

Runs only tests tagged with wip (About tags and tests).

make test.wip

Runs all tests, outputs coverage and generates an html report.

make test.cover

Runs and watches all tests or those tagged with wip

make test.watch
make test.wip.watch

Code analysis commands

Because some of this commands are executed in the lint.yml workflow we recommend to run make check before applying changes to avoid conflicts in the CI. However, git hooks should notify errors and prevent commiting conflicting code when properly installed.

Formats code and analyzes code consistency, best practices and suggest refactoring opportunities.

make lint

Similar to make lint but runs strictly: checks the code is properly formatted.

make check.lint

Runs all available checks. Useful to test a branch before commiting.

make check

Docker commands

There are a group of commands that let developers test a production like distribution of the application, using docker. Copy the .env.prod.example to an .env.prod file and fill in the missing values before trying the commands below.

Run the docker release command to build and run a new, fresh container.

make docker.release

Use docker rerun to stop any running container. This is useful to test a new .env.prod configuration without having to rebuild the whole project.

make docker.rerun

Check the logs of the container that's currently running

make docker.logs

Development server

Once the environment file and the project is properly set up, a development server can be started using the make server command.

• Visit localhost:4000 from your browser to access the application main page.
• Visit localhost:4000/dev/dashboard from your browser to access a development dashboard with information about your app.

License

AGPL v3.0