-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
move contributing info into its own file
- Loading branch information
1 parent
636be95
commit ab8c5fa
Showing
2 changed files
with
137 additions
and
95 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,136 @@ | ||
| Overview | ||
| ======== | ||
|
|
||
| Everyone contributing to this repo should read this document before doing | ||
| anything else: [Important](docs/Important.md) | ||
|
|
||
| For specialized instructions with development related tasks (to save you time | ||
| trying to do various things): [Dev HowTo](docs/Dev-HowTo.md) | ||
|
|
||
| Many code standards and conventions can be picked up from existing patterns in | ||
| the code but it is advisable to use this resource as well: | ||
| [Code Standards](docs/Code-Standards.md) | ||
|
|
||
| If you're looking for specific "Getting Started" instructions for any of the | ||
| sub-projects in this monorepo (like the VS Code extension) then look at those | ||
| specific README.md files. | ||
|
|
||
| Requirements | ||
| ------------ | ||
|
|
||
| 1. Node v18.19.0 (see `Running the App (using source code)` below) | ||
| 2. NPM v10.2.3 | ||
| 3. PostgreSQL 16.3 for storing data: | ||
| `https://www.enterprisedb.com/downloads/postgres-postgresql-downloads` | ||
| (Windows 10 / Mac OS X) | ||
| `https://computingforgeeks.com/install-postgresql-12-on-ubuntu/` | ||
| (Ubuntu with links to other distros) | ||
| 4. VSCE v2.15.0 (for building VSIX file for VS Code extension) | ||
|
|
||
| Recommendations | ||
| --------------- | ||
|
|
||
| VS Code is the editor of choice for this project (v1.71.2 or newer). | ||
| - Make sure to install the recommended workspace extensions. | ||
|
|
||
| Running the App (using source code) | ||
| ----------------------------------- | ||
|
|
||
| 1. Ensure the expected version of Node is active- you can use `nvm use` if you | ||
| have that installed or an equivalent method (use .nvmrc to see actual | ||
| supported version). | ||
| 2. Set up dependencies: | ||
| - at root level: `npm ci` | ||
| 3. Build the app: | ||
| - at root level: `npm run build-all` | ||
| 4. Set up PostgreSQL (you can use these steps or do it the way `setup.sql` | ||
| specifies - one inconsistency is "superuser" so it appears that it isn't | ||
| actually needed and either "y" or "n" will do): | ||
| - `sudo -u postgres createuser --interactive` | ||
| - role: `atoll` | ||
| - superuser: `n` | ||
| - allow to create databases: `y` | ||
| - allow to create new roles: `y` | ||
| - `sudo -u postgres psql` | ||
| - `\du` to see the user created | ||
| - `ALTER USER atoll PASSWORD '{pwd}'` (pick a password- you'll use this | ||
| later as well - `setup.sql` specifies `lim3atoll` but it is recommended | ||
| that you change this for security reasons!) | ||
| - `exit` (`\q` should work too) | ||
| - Restart PostgreSQL server | ||
| - Linux: `sudo service postgresql restart` | ||
| - Mac: `sudo -u postgres /Library/PostgreSQL/16/bin/pg_ctl -D /Library/PostgreSQL/16/data restart` | ||
| - `sudo -u postgres createdb atoll` | ||
| - if you see `could not change directory to ...` you can ignore that error | ||
| - `sudo -u postgres psql` | ||
| - `ALTER DATABASE atoll OWNER TO atoll;` | ||
| - `\p` to see that the command was executed (it will repeat the line above) | ||
| - `\q` to quit | ||
| 5. If you'd like to restore from a backup using pgAdmin 4, you can do that at | ||
| this step. However, first time set up will require you to follow the | ||
| incomplete steps in `setup.sql` (up to, but not including, the "RUN THE APP" | ||
| step). | ||
| 6. Set up environment variables: | ||
| - set ATOLL_DATABASE_URL to the database connection string | ||
| (it should look something like this replacing "{pwd}" with | ||
| atoll user password: `postgres://atoll:{pwd}@localhost:5432/atoll`) | ||
| - set ATOLL_DATABASE_USE_SSL to "true". | ||
| - set ATOLL_AUTH_KEY to something unique for security reasons | ||
| (come up with an obscure value that doesn't follow a typical pattern- | ||
| you'll lever have to look this up so it can anything at all). | ||
| 7. Run the app to create the database structure: | ||
| - at root level: `npm start` | ||
| - watch the output | ||
| - if it was successful you'll see: | ||
| "Database & tables created!" | ||
| - kill the app (if you haven't restored from backup). | ||
| 8. Only needed if you've not restored from backup: | ||
| 1. Setting up atoll user in database (not needed if you've restored from | ||
| backup): | ||
| - at root level: `npm run setup-database` | ||
| - if it was successful you'll see: | ||
| "Executed SQL statement to set up test user account successfully." | ||
| 2. Set up sample data (not needed if you've restored from | ||
| backup): | ||
| - use pgAdmin or psql to execute the script `data.sql` | ||
| 3. Run the app: | ||
| - at root level: `npm start` | ||
| 9. Verify that the app is running successfully: | ||
| - console output will have something like | ||
| `App is running: http://localhost:8500` at the start | ||
| so you know what URL to use in the browser. | ||
| - the sample script created a user with login `test` and password `atoll`, so | ||
| you should be able to use those credentials to login | ||
|
|
||
| Running the App (using source code + Docker) | ||
| -------------------------------------------- | ||
|
|
||
| 1. At root level: `npm ci` | ||
| 2. Build app and create docker image: `npm run docker-pkg:web-app` | ||
| 3. Start docker containers using compose: `npm run start-docker:web-app` | ||
|
|
||
|
|
||
| Working with the Monorepo | ||
| ========================= | ||
|
|
||
| Adding Dependencies | ||
| ------------------- | ||
|
|
||
| This monorepo uses npm workspaces. If you're unfamiliar with using workspaces | ||
| we recommend you read the npm documentation first. Some tips are provided | ||
| below, but it is best that you understand how they work fully. | ||
|
|
||
| Please make sure to add the dependency at the right level. | ||
|
|
||
| You have 2 choices: | ||
| 1. install it globally so that all packages can use that dependency (bear in | ||
| mind that they will use the exact same version when it is global). | ||
| For example, `npm i prettier@latest -D` | ||
| 2. install it at the workspace package level so that individual packages can | ||
| either use a different version or not use it at all. | ||
| For example, `npm i [email protected] -w packages/shared` | ||
|
|
||
| In general, if you're not sure, you should pick option 2. | ||
|
|
||
| If you wish to refresh packages for a specific workspace you can use something | ||
| like: `npm i -w=packages/vscode-extension` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters