Merge pull request #65 from JDIZM/JDI-15-support-workspaces

JDI 15 support workspaces

Author: JDIZM

.env.example

@@ -1,19 +1,17 @@
-NODE_ENV=development
+NODE_ENV=dev
 APP_URL=http://localhost:4000
 PORT=4000
 
 ###
 ## Database
 ###
-# replace with host.docker.internal if using docker for database and the app is running on host
-# POSTGRES_HOST=host.docker.internal
-POSTGRES_HOST=localhost
+POSTGRES_HOST=db
 POSTGRES_USER=postgres
 POSTGRES_PASSWORD=example
-POSTGRES_DB=test
+POSTGRES_DB=postgres
 
 ###
 ## Supabase config
 ###
-SUPABASE_URL=https://xxxxx.supabase.co
-SUPABASE_PK=
+SUPABASE_URL=https://example.supabase.co
+SUPABASE_PK=example-key

.eslintrc.cjs

@@ -4,25 +4,32 @@ module.exports = {
     es2022: true,
     node: true
   },
+  parser: "@typescript-eslint/parser",
   extends: [
     // By extending from a plugin config, we can get recommended rules without having to add them manually.
     "eslint:recommended",
     "plugin:import/recommended",
     "plugin:@typescript-eslint/recommended",
+    "plugin:import/errors",
+    "plugin:import/warnings",
+    "plugin:import/typescript",
     // This disables the formatting rules in ESLint that Prettier is going to be responsible for handling.
     // Make sure it's always the last config, so it gets the chance to override other configs.
     "eslint-config-prettier",
     "prettier"
   ],
+  plugins: ["@typescript-eslint", "import"],
   settings: {
     // Tells eslint how to resolve imports
     "import/resolver": {
       // using the newer eslint-import-resolver-typescript plugin
       // see: https://www.npmjs.com/package/eslint-import-resolver-typescript
-      node: true,
+      node: {
+        extensions: [".js", ".jsx", ".ts", ".tsx", ".d.ts"]
+      },
       typescript: {
-        alwaysTryTypes: true
-        // project: "./tsconfig.json" // relative to project root.
+        alwaysTryTypes: true,
+        directory: "./tsconfig.json"
       }
     },
     "import/parsers": {
@@ -32,7 +39,7 @@ module.exports = {
   rules: {
     // Add your own rules here to override ones from the extended configs.
     "@typescript-eslint/no-explicit-any": "warn",
-    "arrow-parens": "error"
+    "arrow-parens": ["error", "always"]
   },
   overrides: [
     {

.gitignore

@@ -2,4 +2,6 @@ node_modules
 dist
 coverage
 .env
-package-lock.json
+pnpm-lock.yaml
+logs
+*.log

Dockerfile

@@ -1,17 +1,50 @@
-# use a slimmer alpine image to consume less memory
-# https://viralganatra.com/docker-nodejs-production-secure-best-practices/
-FROM node:20-alpine
+FROM node:20-alpine as base
+
+ENV PNPM_VERSION=9.1.0
+
+RUN npm install -g pnpm@$PNPM_VERSION
 
 WORKDIR /app
 
 # install deps first so we can cache them
-COPY package*.json ./
-RUN npm ci && npm cache clean --force
+COPY package*.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile
+
+FROM base AS builder
+
+WORKDIR /app
 
-# build the app
 COPY . .
+
 RUN mkdir dist
-RUN npm run build
+
+RUN pnpm build
+
+FROM base AS runner
+
+WORKDIR /app
+
+RUN addgroup --system --gid 1001 express
+RUN adduser --system --uid 1001 express
+
+COPY --from=builder --chown=express:express /app/node_modules /app/node_modules
+COPY --from=builder --chown=express:express /app/dist /app/dist
+COPY --from=builder --chown=express:express /app/package.json /app/package.json
+
+USER express
+
+EXPOSE 4000
+
+FROM runner AS dev
+
+WORKDIR /app
+
+COPY --from=builder --chown=express:express /app/.env /app/.env
 
 CMD ["node", "./dist/server.mjs"]
 
+FROM runner AS prod
+
+WORKDIR /app
+
+CMD ["node", "./dist/server.mjs"]

README.md

@@ -17,7 +17,20 @@
 - [helmet](https://helmetjs.github.io/)
 - [cookie-parser](https://www.npmjs.com/package/cookie-parser)
 
-A simple node/express backend api template.
+A node/express backend API template for getting started with a new project that includes authentication, permissions, and a database configured to
+use [Supabase](https://supabase.io/) or a local/cloud Postgres database.
+
+This comes pre-defined with a workspaces model that allows accounts (users) to create workspaces and invite other profiles (users presence within a workspace) to access the workspace (membership). see the [Permissions](#Permissions) section for more information on how permissions are defined.
+
+The contents of a workspace is not defined in this template and can be customized to suit the needs of the project.
+
+## ESM Node
+
+https://www.typescriptlang.org/docs/handbook/esm-node.html
+
+This project has been setup to use ESM Node. This allows us to use ES6 imports in Node.
+
+This uses [tsx](https://github.com/esbuild-kit/tsx) as a dev server and [pkgroll](https://github.com/privatenumber/pkgroll) to bundle and build the project.
 
 ## Requirements
 
@@ -29,15 +42,11 @@ To install volta run the following command in the terminal.
 curl https://get.volta.sh | bash
 ```
 
-## ESM Node
-
-https://www.typescriptlang.org/docs/handbook/esm-node.html
-
-This project has been setup to use ESM Node. This allows us to use ES6 imports in Node.
+You will need a Postgres database to run this project. You can use Docker to run a Postgres database or use a service like [Supabase](https://supabase.com/).
 
-This uses [tsx](https://github.com/esbuild-kit/tsx) as a dev server and [pkgroll](https://github.com/privatenumber/pkgroll) to bundle and build the project.
+See the [Database](#Database) section for more information on how to configure the database connection.
 
-## ENV
+### ENV
 
 Create a .env file in the root of the project and copy the contents of .env.example into it.
 
@@ -47,20 +56,11 @@ cp .env.example .env
 
 see the section on [Deployment with DigitalOcean](#deployment-with-digitalocean) for more information on how to configure the environment variables for deployment in different environments (eg. development and production).
 
-## Setup
+### Install dependencies
 
 ```
 # install dependencies
 npm i
-
-# start the dev server
-npm run dev
-
-# make sure to configure the env variables
-cp .env.example .env
-
-# view it running on localhost
-curl localhost:3000
 ```
 
 ## Testing
@@ -75,45 +75,39 @@ It's also recommended to install the [vitest extension for vscode](https://marke
 
 You can view the database with `npx drizzle-kit studio` or `npm run studio`.
 
-You can spin up a local copy of the database with `docker-compose` but this is not required when using Supabase.
+You can spin up a local copy of the database and application with `docker-compose` but this is not required when using the Supabase db.
 
 ```
 docker compose up -d
 ```
 
-If you are using the local database and running the application within docker on the host machine you will need to replace the `POSTGRES_HOST` from `localhost` to `host.docker.internal` in the .env file.
-
-```
-POSTGRES_HOST=host.docker.internal
-```
+Alternatively you can create a local network and connect the containers to the network.
 
-## Build with docker
+```bash
+docker network create mynetwork
 
+docker run --network mynetwork --name mypostgres -d -p 5432:5432 -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=example -e POSTGRES_DB=postgres postgres:15
 ```
-# build the app
-npm run build
-
-# build with docker
-docker build . --tag node-express-esm
 
-# or to build with a specific platform
-docker build . --tag node-express-esm --platform linux/amd64
+Then when running the application in docker you can connect to the database with the container name.
 
-# start the docker container
-docker run -d -p 3000:3000 node-express-esm
+```bash
+POSTGRES_HOST=mypostgres
+```
 
-# view it running on localhost
-curl localhost:3000
+Then run the application in docker and connect to the same network.
+```bash
+docker run --network mynetwork --name node-express -d -p 4000:4000 node-express
 ```
 
+Note: If you are using a local database and running the application within docker on the host machine you will need to set `POSTGRES_HOST=host.docker.internal` in the .env file. [Read the docs for more info](https://docs.docker.com/desktop/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host)
+
 ### Migrations
 
 When the schema/model is changed make sure to create a new migration and run it against the db.
 
 1. Create a new migration
 
-<!-- TODO create a named migration and pass additional flag to npm. -->
-
 ```
 npm run migrate:create
 
@@ -139,6 +133,28 @@ npm run seed
 
 Be sure to update the seeds as new migrations are added.
 
+## Build with docker
+
+```
+# build the app
+npm run build
+
+# build with docker
+docker build . --tag node-express
+
+# or to build with a specific platform
+docker build . --tag node-express --platform linux/amd64
+
+# or build a specific stage eg dev
+docker build . --target dev --tag node-express
+
+# start the docker container
+docker run -d -p 4000:4000 node-express
+
+# view it running on localhost
+curl localhost:4000
+```
+
 ## Import aliases
 
 Aliases can be configured in the import map, defined in package.json#imports.
@@ -153,24 +169,28 @@ This project uses JWT bearer token for authentication. The claims, id and sub mu
 
 How permissions work.
 
-A resource will have a permission level. A user will have a role/claim.
+A resource will have a permission level for each route method based on users role within the workspace. Workspace permissions can be defined in `./src/helpers/permissions.ts`.
+
+Workspace permissions:
+Admin: Highest level of access to all resources within the workspace.
+User: Regular user with limited permissions.
 
-Routes will have their permission level defined in `./src/helpers/permissions.ts`
+Resource permissions:
+Owner: Has access to their own resources
 
-When a user makes a request to a route the route will check the user's role/claim against the permission level of the resource.
+Account permissions:
+SuperAdmin: Has access to all super only resources.
 
-### Route permission levels
+### Workspace route permission levels
 
-1. Owner - Route can only be accessed by the owner of the resource. Defined by the id of the resource being accessed matching the id of the user making the request.
-2. User - Can access all resources with user permissions.
-3. Admin - Can access all resources.
+Ensure every request that requires workspace permissions includes a workspace context. This can be done using the `x-workspace-id header`.
 
-### Claims / Roles
+Passing the `x-workspace-id` header will allow the user to access the workspace resources if they are a member of the workspace with a sufficient role.
 
-A claim is defined when the user is created which defines the user's role and permissions level.
+A role/claim is defined when the account is added to the workspace as a member.
 
-1. User - default user permissions
-2. Admin - admin permissions
+1. User - Can access all resources with user permissions.
+2. Admin - Can access all resources.
 
 ## Supabase Auth
 

docker-compose.yml

@@ -2,6 +2,14 @@
 version: "3.1"
 
 services:
+  app:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    env_file:
+      - .env
+    ports:
+      - "4000:4000"
   db:
     image: postgres
     restart: always

drizzle.config.ts

@@ -1,19 +1,20 @@
 import type { Config } from "drizzle-kit";
 // drizzle requires the ts extension to import config.
 import { config } from "./src/config.ts";
-import { logger } from "./src/helpers/logger.ts";
+import { logger } from "./src/helpers/index.ts";
 
-logger.info("config", config);
+logger.info({ msg: "config", config });
 
 export default {
+  dialect: "postgresql",
   schema: "./src/schema.ts",
   out: "./drizzle",
-  driver: "pg",
   dbCredentials: {
     host: config.db_host,
     user: config.db_user,
     port: 5432,
     password: config.db_password,
-    database: config.db_name
+    database: config.db_name,
+    ssl: config.env !== "dev"
   }
 } satisfies Config;