ExCommerce

Elixir Marketplace Prototype

Development

Requirements

The ex_commerce 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.
• DB_USERNAME_TEST: same as DB_USERNAME for test development.
• DB_PASSWORD_TEST: same as DB_PASSWORD for test development.

Mailing Service

• EX_COMMERCE_FROM_NAME: Sender name.
• EX_COMMERCE_FROM_EMAIL: Sender email.
• SMTP_HOST: The smtp hostname.
• SMTP_PORT: The smtp port (1025 by default)
• SMTP_USERNAME: The authentication username.
• SMTP_PASSWORD: The authentication password.

Cloudex credentials

• CLOUDEX_API_KEY: the cloudex api key.
• CLOUDEX_SECRET: the cloudex secret key.
• CLOUDEX_CLOUD_NAME: the cloudex name of the cloud.

The assigned directory for uploads

• UPLOADS_PATH: the assigned path for uploads.

Captcha credentials

• RECAPTCHA_PUBLIC_KEY: the public key for the captcha service.
• RECAPTCHA_SECRET: the secret key for the captcha service.

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

Development server

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

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

License

AGPL v3.0