SpencerKaiser/TS-API

After cloning, make the following case sensitive global text replacements:

• PACKAGE -> your lowercase package name (follow npm naming conventions, e.g., lowercase, no spaces)
• APP_NAME -> Your human friendly app name

Don't forget to manually rename PACKAGE.code-workspace, replacing PACKAGE for the name of your project.

Finally, delete this section from the README and run yarn to properly link dependencies.

• Node 18+

• Yarn v1

  This project is a monorepo, so Yarn was chosen for better dependency management

1. Install dependencies

   yarn

2. Copy packages/api/.env.sample to packages/api/.env.local

   cp packages/api/.env.sample packages/api/.env.local

   PostgreSQL

   If you don't have Postgres installed already, see the Installation and Use section below.

   After installing, create a DB with the name PACKAGE (or use another name and override DATABASE_URL in your .env.local).

   Installation and Use

   macOS

   We recommend using Postgres.app as the installation doesn't require a password and is generally easier to use that the traditional Postgres app below.

   Windows/macOS/Linux

   During the installation process (if you follow the steps on postgresql.org), you will be prompted to set a password - make sure to use something you'll remember.

   Viewing/Editing the DB

   If you'd like a visual way of viewing or editing your local database, try using TablePlus.

   Seeding the Database

   You can seed the database using the mikro-orm/cli tool.

   You can drop, create, migrate, and seed the database any time you need with this command (run from packages/api):

   • yarn mikro-orm migration:fresh --seed DatabaseSeeder

   ⚠️ NOTE: Running the above command will delete all data in your database

   Database migrations

   To run migrations locally, use yarn migrate from the root. If you ever want to replace your db contents with a fresh setup, run yarn db:fresh.

   Updating Mikro-ORM

   The process to update all packages is a little painful because ALL Mikro-ORM dependencies across BOTH packages must be kept in sync. Run both commands below (after modifying the version to match whatever target needed)

   # API
   yarn workspace @PACKAGE/api add @mikro-orm/core@^6.0 @mikro-orm/knex@^6.0 @mikro-orm/postgresql@^6.0 mikro-orm@^6.0
   
   # DB
   yarn workspace @PACKAGE/database add @mikro-orm/cli@^6.0 @mikro-orm/core@^6.0 @mikro-orm/knex@^6.0 @mikro-orm/migrations@^6.0 @mikro-orm/postgresql@^6.0 @mikro-orm/seeder@^6.0 mikro-orm@^6.0

   Restoring a Production DB locally

   In order to debug an issue locally, it can be helpful to mirror the prod DB locally. When doing so, make sure to avoid actions that will trigger text messages because user data is REAL. Always re-seed the DB after fixing your issue to avoid sending erroneous texts.

   ⚠️ WARNING: Make sure to follow these steps closely. Making an error below has the potential to overwrite production data if your token allows for write access.

   1. Open TablePlus (no need to connect to a DB)
   2. Go to File > Backup (Windows steps TBD), choose your production database connection
   3. Select the prod database
   4. Make sure the Postgres version is PostgreSQL 14.0 and set the options to be --no-owner and --format=custom
   5. Click Start Backup
   6. (OPTIONAL) Drop all current data to ensure your local copy is an exact replica, otherwise some local data may persist
      1. Open a connection to your local database, select all tables and functions (command + a on macOS), right click, and choose "Delete"
      2. When prompted, check the option for Cascade and click OK
   7. Wait for the backup to finish and then go to File > Restore (Windows steps TBD), choose your local database connection
   8. Remove all flags from the left hand side (primarily, --single-transaction which will cause your restore to fail on conflict)
   9. Select your database on the right hand side
   10. Click Start restore

   Restarting Table Sequences

   If you add data manually to your database (through a tool like TablePlus) and do NOT let Postgres assign an id automatically, you will disrupt the sequence for that table that determines the next available id to assign. If that happens, perform the following queries to restart it.

   Find the appropriate sequence name:

   SELECT sequence_schema, sequence_name
   FROM information_schema.sequences
   ORDER BY sequence_name;

   Restart the sequence with a new id:

   ALTER SEQUENCE "YOUR_TABLE_SEQUENCE" RESTART WITH THE_NEXT_ID_TO_ASSIGN;

   (e.g., ALTER SEQUENCE "Provider_id_seq" RESTART WITH 11;)

   Slack

   To configure Slack notifications for certain events, create a Slack app use the following manifest after selecting From an app manifest (NOTE: watch out for whitespace issues when copying):

   display_information:
     name: APP_NAME Dev (YOUR_FIRST_NAME)
     description: Dev bot for testing integrations
     background_color: '#000000'
   features:
     bot_user:
       display_name: APP_NAME (YOUR_FIRST_NAME)
       always_online: false
   oauth_config:
     scopes:
       bot:
         - chat:write.public
         - chat:write
   settings:
     org_deploy_enabled: false
     socket_mode_enabled: false
     token_rotation_enabled: false

   After creating the app, use the sidebar and go to Install App and request to install the app to your workspace. Once approved, head back to this section and Install to workspace.

   After installation, copy the Bot User OAuth Token value (starting with xoxb-) and use that for your SLACK_BOT_TOKEN.

   Channel IDs can be obtained by right clicking a channel in the sidebar and removing the last path value from the URL.

3. Start the development server

   yarn dev

   When you see this success message, open the url to load the site

   🚀 Listening at http://localhost:3000

   The server starts before Next.js finishes compiling, so the first time may take a little bit to load

4. After your initial setup, you'll need to run your database migrations:

   yarn migrate
   

5. Start developing

APP_NAME is containerized to make deployment efficient and to prevent vendor-dependence for our cloud environment

1. Installing relevant dependencies
2. Duplicate .env.docker.sample as .env.docker and modify values as needed
3. Downloading Docker Desktop and start it
   • Optionally modify Settings > Resources > Advanced to provide more resources to Docker and speed up your build commands
4. Run yarn docker:build from the root to build your image
5. Run yarn docker:run to start your container
6. Visit localhost:3001 to use the app running in Docker

packages/api/.env.local is used as the base for all environment variables but .env.docker will override any specified environment variables as needed.

On macOS Postgres user/pass is typically not required. If you do not use one in your API .env.local, you WILL need to specify one in .env.docker; the password is typically blank (no value needed) and your username is typically your machine user (use whoami in terminal).

If you are unable to start your Docker app, make sure the steps above have been followed, then:

• Check the accuracy of your .env.docker and packages/api/.env.local values (the former will override the latter)
• Make sure no quotes are used in either file; Docker does not remove them and your value will include them
• You can use Docker Desktop to inspect the environment: Docker Desktop > Containers / Apps > PACKAGE (environment variables can be found on the Inspect tab)