The goal of this project is to provide a system for collecting aid offers and organizing them into pallets appropriate for a shipment. Using the system, Distribute Aid administrators can create shipments, aid donors can organize their aid for donation into offers for a shipment and provide the information necessary for a Distribute Aid hub coordinator and logistics coordinator to process it for international shipping to refugees.
Key documents:
The main saga branch is deployed automatically to CleverCloud by CI. Staging can be accessed here:
https://shipment-tracker-saga.distributeaid.dev/
First, please read our contribution guidelines.
Development tasks are managed in the github issues for this repository. The issues themselves are fairly light on detail in favor of a simple description of scope (i.e. the conditions for the task being considered "done"). For specifics on task requirements, please reference the project requirements document early and often.
Issues tagged front end will also be tagged with either needs UI mock, indicating the task still needs design work to be ready for development, or has UI mock indicating it's ready for dev work.
When you begin working on an issue, please self-assign or comment on it indicating you're beginning work to avoid duplicate effort.
When you're ready to submit your code, open a pull request with "Closes #X" to link the relevant issue. When your PR is approved by at least one maintainer it is ready to submit.
It's easy for the intention of code review comments to be unclear or get misinterpreted. To help with communication, reviewers are encouraged to use conventional comments and explicitly indicate that comments are (blocking), where the discussion must be resolved for PR to be merged, or (non-blocking) where resolving the discussion is optional for the implementer.
Reviewers should grant approval if they do not feel additional review is necessary before merging. This does not necessarily mean no more changes are required before merging, but that any further changes are expected to be minor enough to not require review.
If the pull request does not require additional changes, the reviewer should merge it immediately after approving. Otherwise, the pull request author should merge (if able) once they have addressed all comments marked (blocking) or nit. Contributors are encouraged to at least reply to (non-blocking) and (if-minor) comments if they do not address them with code changes.
We provide a pre-configured environment which is configured so you are ready to run the test suite and the development server.
You can launch a dedicated environment for directly from GitHub using Codespaces: select the green Code dropdown and then New codespace. Learn more about Codespaces.
After your DevContainer has been bootstrapped, you can run the tests by opening a Terminal in VS Code in the browser (Select View -> Terminal, or press Ctrl+`), and then run the command:
npm test
Because of limitiations with the networking (specifically setting up the neccessary hostnames for proper CORS), running the development server in codespaces is not yet possible.
You can launch a dedicated environment after cloning the project in Visual Studio Code: follow the installation instructions (you need the Remote Development Extension pack, then select the green Remote icon and then Reopen in Container. Learn more about Remove development in Containers.
After your DevContainer has been bootstrapped, you can run the tests by opening a Terminal in VS Code in the browser (Select View -> Terminal, or press Ctrl+`), and then run the command:
npm test
You can also run the development server and the frontend. Open a new terminal and start the development server:
yarn dev
Then, open a second terminal, navigate to the ./frontend directory and run:
yarn install --frozen-lockfile
yarn start
You can click on the printed URLs to open them in a browser.
-
Install Node.js 16:
-
Switch to Node 16 if needed. nodenv should do it automatically, but with nvm you'll need to run
nvm use 16 -
Install the dependencies:
yarn install --frozen-lockfile -
Build the project:
yarn build -
Install postgresql:
brew install postgresql@13 -
Start postgresql:
brew services start postgresql@13 -
Launch the PostgreSQL CLI:
psql -d postgres -
Run all these commands consecutively:
CREATE USER distributeaid_test; ALTER USER distributeaid_test PASSWORD 'distributeaid_test'; CREATE DATABASE distributeaid_test; CREATE USER distributeaid; ALTER USER distributeaid PASSWORD 'distributeaid'; CREATE DATABASE distributeaid_dev; -
Migrate the database:
npx sequelize-cli --env=test db:migrate npx sequelize-cli --env=development db:migrate
-
Start the backend:
yarn dev
You're now ready to run the frontend of the app:
- Navigate to the
frontenddirectory - Make sure you're using Node 16
- Install the dependencies:
yarn install --frozen-lockfile - Start the dev server:
yarn start
You should now be able to run the project locally!
If this is your first time, you'll probably want to create an account. You can use the UI to do that:
- Navigate to the login page: http://localhost:8080/
- Register a new account
- When asked for an email confirmation, check your terminal! There will be a confirmation token.
- Once confirmed, enter your password again to log in.
- To make yourself an admin, run:
node cli admin <youremail@domain.com>
You can seed the database by running the end-to-end tests following these instructions.
See the docs folder.
Shipment Tracker is a full stack TypeScript web app backed by a PostgreSQL database.
General tools:
Back end:
Front end: