Skip to content

README.example.md

Latest commit

 

History

History
221 lines (160 loc) · 7.99 KB

README.example.md

File metadata and controls

221 lines (160 loc) · 7.99 KB

Project Name Human

Description of the project. What is it solving? Who are the users?

This section should include any business related explanation that helps understand the context of the project. It could be an excellent idea to include a dictionary of terms, a color legend or a user roles explanation.

  • App: staging | production
  • Scalingo: staging | production
  • Asana:
  • URL to Abtion's own related git repositories (frontend / backend / admin area / microservices)
  • Harvest:
  • CI:
  • Client name, and if possible, contact details.
  • 1Password:
  • Error Tracking:
  • Activity Monitoring:
  • Logging:
  • Email Service:
  • Client: IT person contact details

If the project is using some special external services (MitID, oAuth, Customer API, etc.) give a short description here. Example: The app is using MitID to authenticate all its users.

Development

Requirements

Configuration

Environment

Env files are ONLY loaded for non-production envs.

Otherwise they follow AdonisJS's environment variables docs.

Two-factor auth env vars:

  • APP_ISSUER (defaults to adonis) – issuer label for TOTP secrets
  • WEBAUTHN_RP_ID – relying party id/hostname used for WebAuthn
  • WEBAUTHN_ORIGIN – full origin for WebAuthn (e.g. http://localhost:3000)
  • WEBAUTHN_RP_NAME – human-friendly relying party name

Mail env vars:

  • SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD – SMTP connection details
  • MAIL_FROM_ADDRESS – sender email address (must be a valid email)
  • MAIL_FROM_NAME – sender display name

These are required — the app will not start without them.

Environment SMTP setup
Development smtp4dev via docker compose (localhost:2525, inbox at http://localhost:5000)
Staging Mailtrap.io sandbox (login: admin@abtion.com, credentials in 1Password)
Production Requires a real SMTP provider (e.g. Postmark, SendGrid)

Emails are queued, so keep a worker running when testing mail locally:

node ace jobs:listen --queue=default,mails --concurrency=1,5

Setup

The recommended way to run the project is to use docker compose for databases and asdf for installing runtimes.\

For running the project locally:

  1. In one terminal window:

    docker compose up

  2. In another terminal window:

    asdf install # To install runtimes
bin/setup # To install dependencies and initialize the database
npm run dev # To run the webserver

  3. The project can now be accessed at http://localhost:3000

Other setups

It is also possible to run everything locally, but it requires locally setting up the services specified in the docker-compose.yml.
It will also require changes to the connection string env vars.

Running tests

node ace test # Run all tests
node ace test --coverage-text # Print coverage
node ace test --coverage-html # Generate HTML coverage report (useful alongside `npx http-server coverage`)
node ace test browser # Run only browser test suite. Other suites are: functional, unit (and more if added)
node ace test --files [partial_file_name] # Run specific test files

NB: While the test commands might collect coverage (if specified), they do not check that the coverage meets the thresholds.

Checking coverage

Coverage thresholds (and other settings) are specified in the backend/frontend coverage configuration files: .c8rc.json, .nycrc.json.

Coverage is automatically checked in CI.
To check locally, run:

npx c8 check-coverage # Check backend coverage
npx nyc check-coverage # Check front-end coverage

Available scripts

Contrary to other Abtion projects, not all files under bin are executable.
Some are instead used by AdonisJS' ace tool:

bin/console.ts # AdonisJS commands
bin/server.ts # AdonisJS server
bin/test.ts # AdonisJS tests

Otherwise regular "shebang" type scripts are added:

bin/setup # For setting up the project

Custom commands for ace (similar to rake commands for rails) are located inside commands and include:

node ace db:create # Create dev and test dbs
node ace db:drop # Drop dev and test dbs
node ace db:migrate # Migrate dev (or test) db
node ace db:rollback # Rollback dev (or test) db
node ace make:migration # Create a db migration using kysely's migration language

There are also many other built-in commands that can be inspected by just running node ace, for instance:

node ace make:* # Lots of options, like `rails g`
node ace repl # Similar to `rails c`
node ace list:routes # Similar to `rails routes`
node ace jobs:make # Make a new type of background job

Deployment

Deploy on Scalingo

Need a Scalingo app? Click the button above to create one. It deploys from the base template — once created, connect the app to this repo for subsequent deploys. See Configure CD for detailed steps.

The app is hosted on Scalingo. Deploys happen automatically when pushing to the connected branch.

  • Staging deploys from main.
  • Production deploys are triggered manually.

Environment variables are managed in the Scalingo dashboard.

Good to know

Notable changes to default AdonisJS template

The project was initialized:

  • As a web project
  • With React (Inertia) front-end
  • PostgresQL was selected as database.

Otherwise the following changes where made:

  • Railsification
    • Env files made more like our rails template
    • Setup script added: bin/setup
    • Scripts for creating and dropping databases
    • config/database.ts: A single place for db config for multiple envs
    • The concept of a "base" error on form handlers
      • Triggered by throwing a FormError in a controller
      • Shown with the BaseFormError component
  • Database
    • Kysely used instead of lucid
      • Allows us to have types in react
  • Tailwind added + setup for component library compatibility
  • Development server running on 3000 because we are used to that
  • Tests
    • Test server port changed to not conflict with development server
    • Automatically run pending migrations
    • Code coverage has been set up (Use --coverage-text flag when running tests)
  • Authentication implemented
  • TOTP + Webauthn auth
  • Landing page and simple user management implemented
  • Background jobs implemented through adonisjs-jobs (community package)
    • UI available at /jobs

Third party services

Name of the third party

  • Description:
  • Auth: Where can it be found. E.g. .env file
  • Documentation:
  • Web interface:
  • IT Contact person: