:fix devcontainer, add documentation

PalisadoesFoundation · Jan 8, 2025 · 871d307 · 871d307
1 parent 0b2dcfd
commit 871d307
Show file tree

Hide file tree

Showing 18 changed files with 1,189 additions and 477 deletions.
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
@@ -8,7 +8,6 @@
 			"extensions": [
 				"biomejs.biome",
 				"esbenp.prettier-vscode",
-				"ms-azuretools.vscode-docker",
 				"GraphQL.vscode-graphql",
 				"GraphQL.vscode-graphql-syntax",
 				"redhat.vscode-yaml"
@@ -68,10 +67,11 @@
 		"ghcr.io/devcontainers/features/github-cli": {}
 	},
 	"init": true,
-	"initializeCommand": "cp ../.env_files/.env.devcontainer ../.env",
+	"initializeCommand": "cp -n ./envFiles/.env.devcontainer ./.env",
 	"name": "talawa_api",
 	"overrideCommand": true,
-	"postCreateCommand": "fnm install && fnm use && corepack enable npm && corepack enable && corepack install",
+	"postCreateCommand": "sudo chown talawa:talawa ./.pnpm-store ./node_modules && fnm install && fnm use && corepack enable npm && corepack enable && corepack install && pnpm install --prod=false && pnpm push_drizzle_schema && pnpm start_development_server",
+	"postStartCommand": "pnpm install --prod=false",
 	"remoteUser": "talawa",
 	"service": "api",
 	"shutdownAction": "stopCompose",

diff --git a/INSTALLATION.md b/INSTALLATION.md
@@ -0,0 +1,48 @@
+# Development environment setup
+
+## Prerequisites
+
+You must have basic competence and experience in the following technologies to be able to set up and work within the development environment of talawa api:
+
+1. Unix based operating systems like linux based distributions, macOS or windows subsystem for linux.
+2. Git
+3. Github
+4. Docker
+5. Docker compose
+6. Visual studio code with devcontainers
+7. Typescript
+8. Node.js
+
+## Our recommendations
+
+Linux based distributions are simply the best platform for a very vast majority of use cases related to software development. As such we recommend using popular linux based distributions like fedora, arch, ubuntu, linux mint, debian etc., for having a better experience during software development.
+
+We make heavy of use docker containers in our workflows. Since, containers are a technology built on top of linux, on non-linux platforms they can only be used by emulating linux where they are ran inside linux based virtual machines. So, you should be aware that there are performance penalties and certain limitations with running containers on platforms like macOS and windows.
+
+Though, many of these penalties and limitations don't apply to windows subsystem for linux. So, if you plan on using windows, at the very least make use of windows subsystem for linux.
+
+## Setup
+
+We provide a mostly automated way of setting up the development environment for talawa api using git, docker and visual studio code as shown in the following video:
+
+<!-- Video link or embed here -->
+
+It is very important that you go through [this](https://code.visualstudio.com/docs/devcontainers/containers) official documentation for working with devcontainers in visual studio code.
+
+# Local production environment setup
+
+Developers working on client applications making use of talawa api can set up and run a production build of talawa api on their systems locally.
+
+## Prerequisites
+
+You must have basic competence and experience in the following technologies to be able to set up and run the production build of talawa api locally on your system:
+
+1. Git
+2. Docker
+3. Docker compose
+
+## Setup
+
+We provide a mostly automated way of running the production build of talawa api locally on your system using git, docker and docker compose as shown in the following video:
+
+<!-- Video link or embed here -->
diff --git a/docker/api.Containerfile b/docker/api.Containerfile
@@ -26,17 +26,20 @@ RUN groupmod -n talawa vscode \
 # Sets read, no write and no execute permissions for the user and the group on `/etc/sudoers.d/talawa` file and no read, no write and no execute permissions for the other.  
 && chmod u=r--,g=r--,o=--- /etc/sudoers.d/talawa \
 && apt-get clean \
-&& rm -rf /var/lib/apt/lists/*
+&& rm -rf /var/lib/apt/lists/* \
+# https://code.visualstudio.com/remote/advancedcontainers/persist-bash-history
+&& mkdir /commandhistory \
+&& touch /commandhistory/.bash_history \
+&& chown -R talawa /commandhistory \
+&& echo "export PROMPT_COMMAND='history -a' && export HISTFILE=/commandhistory/.bash_history" >> /home/talawa/.bashrc
 USER talawa
-ENV PNPM_HOME=/home/talawa/.local/share/pnpm
-ENV PATH=${PNPM_HOME}:/home/talawa/.local/share/fnm:${PATH}
 # Installs fnm.
 RUN curl -fsSL https://fnm.vercel.app/install | bash -s -- --skip-shell \ 
 # Appends the fnm configuration to `/home/talawa/.bashrc` file.
 && echo eval \"\$\(fnm env --corepack-enabled --resolve-engines --use-on-cd --version-file-strategy=recursive\)\" >> /home/talawa/.bashrc
+ENV PATH=/home/talawa/.local/share/fnm:${PATH}
 WORKDIR /home/talawa/api
-
-# This build stage sets up and switches to the `talawa` non root user, sets up pnpm configuration and checks out into the `/home/talawa/api` directory as the working directory.
+
 FROM node:22.12.0-bookworm-slim AS base
 # Used to configure the group id for the group assigned to the non-root "talawa" user within the image.
 ARG API_GID
@@ -52,10 +55,6 @@ RUN userdel -r node \
 && useradd -g talawa -l -m -s "$(which bash)" -u ${API_UID} talawa \
 && corepack enable
 USER talawa
-# Adds `${PNPM_HOME}` environment variable with `/home/talawa/.local/share/pnpm` value to the container.
-ENV PNPM_HOME=/home/talawa/.local/share/pnpm
-# Adds value of `${PNPM_HOME}` environment variable to the `${PATH}` environment variable within the container.
-ENV PATH=${PNPM_HOME}:${PATH}
 WORKDIR /home/talawa/api
 
 FROM base AS non_production

diff --git a/docker/compose.development.yaml → docker/compose.devcontainer.yaml b/docker/compose.development.yaml → docker/compose.devcontainer.yaml
@@ -1,7 +1,7 @@
 # https://docs.docker.com/reference/compose-file/networks/
 networks:
   cloudbeaver:
-# https://docs.docker.com/reference/compose-file/networks/
+# https://docs.docker.com/reference/compose-file/services
 services:
   api:
     # https://docs.docker.com/reference/compose-file/build/
@@ -14,10 +14,16 @@ services:
     depends_on:
       minio:
         condition: service_healthy
-        required: true
+        required: false
+      minio-test:
+        condition: service_healthy
+        required: false
       postgres:
         condition: service_healthy
-        required: true
+        required: false
+      postgres-test:
+        condition: service_healthy
+        required: false
     # https://docs.docker.com/compose/environment-variables/
     # https://docs.docker.com/reference/compose-file/services/#environment
     environment:
@@ -39,20 +45,25 @@ services:
         target: ${API_DEBUGGER_PORT}
     # https://docs.docker.com/reference/compose-file/services/#restart
     restart: unless-stopped
+    user: talawa
     # https://docs.docker.com/reference/compose-file/services/#volumes
     volumes:
-      # - source: api_pnpm_store
-      #   target: /home/talawa/api/.pnpm-store
-      #   type: volume
-      # - target: /home/talawa/api/node_modules
-      #   type: volume
-      - bind:
-          # changes made within the container are reflected on the host and changes made on the host are reflected within the container
-          propagation: shared
-        consistency: cached
+      - consistency: cached
         source: ./
         target: /home/talawa/api
         type: bind
+        # https://code.visualstudio.com/remote/advancedcontainers/persist-bash-history
+      - source: api_bash_history
+        target: /commandhistory
+        type: volume
+        # https://code.visualstudio.com/remote/advancedcontainers/improve-performance#_use-a-targeted-named-volume
+      - source: api_node_modules
+        target: /home/talawa/api/node_modules
+        type: volume
+        # https://code.visualstudio.com/remote/advancedcontainers/improve-performance#_use-a-targeted-named-volume
+      - source: api_pnpm_store
+        target: /home/talawa/api/.pnpm-store
+        type: volume
   caddy:
     # https://docs.docker.com/reference/compose-file/services/#depends_on
     depends_on:
@@ -116,31 +127,45 @@ services:
         name: minio_console
         published: ${MINIO_CONSOLE_MAPPED_PORT:?error}
         target: 9001
-  # https://github.com/minio/minio/issues/13025
   minio-test:
     # https://docs.docker.com/reference/compose-file/services/#ports
     ports:
-      - host_ip: ${MINIO_TEST_API_MAPPED_HOST_IP:?error}
+      - host_ip: ${MINIO_API_MAPPED_HOST_IP:?error}
         name: minio_api
         published: ${MINIO_TEST_API_MAPPED_PORT:?error}
         target: 9000
-      - host_ip: ${MINIO_TEST_CONSOLE_MAPPED_HOST_IP:?error}
+      - host_ip: ${MINIO_CONSOLE_MAPPED_HOST_IP:?error}
         name: minio_console
         published: ${MINIO_TEST_CONSOLE_MAPPED_PORT:?error}
         target: 9001
+    # https://docs.docker.com/reference/compose-file/services/#volumes
+    volumes:
+      - source: minio_test_data
+        target: /data
+        type: volume
   postgres:
     # https://docs.docker.com/reference/compose-file/services/#ports
     ports:
       - host_ip: ${POSTGRES_MAPPED_HOST_IP:?error}
         name: postgres
         published: ${POSTGRES_MAPPED_PORT:?error}
         target: 5432
-  postgres_test:
+  postgres-test:
     ports:
-      - host_ip: ${POSTGRES_TEST_MAPPED_HOST_IP:?error}
+      - host_ip: ${POSTGRES_MAPPED_HOST_IP:?error}
         name: postgres
         published: ${POSTGRES_TEST_MAPPED_PORT:?error}
         target: 5432
+    # https://docs.docker.com/reference/compose-file/services/#volumes
+    volumes:
+      - source: postgres_test_data
+        target: /var/lib/postgresql/data
+        type: volume
 # https://docs.docker.com/reference/compose-file/volumes/
 volumes:
+  api_bash_history:
+  api_node_modules:
+  api_pnpm_store:
   cloudbeaver_data:
+  minio_test_data:
+  postgres_test_data:
diff --git a/docker/compose.testing.yaml b/docker/compose.testing.yaml
@@ -16,7 +16,7 @@ services:
         condition: service_healthy
         # Should be set to false when a third party minio test service could be used in the api service and the `minio_test` compose profile is disabled.
         required: true
-      postgres_test:
+      postgres-test:
         condition: service_healthy
         # Should be set to false when a third party postgres test service could be used in the api service the and the `postgres_test` compose profile is disabled.
         required: true
@@ -40,11 +40,11 @@ services:
     # https://docs.docker.com/compose/environment-variables/
     # https://docs.docker.com/reference/compose-file/services/#environment
     environment:
-      - MINIO_BROWSER=${MINIO_TEST_BROWSER:?error}
+      - MINIO_BROWSER=${MINIO_BROWSER:?error}
         # https://min.io/docs/minio/linux/reference/minio-server/settings/root-credentials.html#envvar.MINIO_ROOT_PASSWORD
-      - MINIO_ROOT_PASSWORD=${MINIO_TEST_ROOT_PASSWORD:?error}
+      - MINIO_ROOT_PASSWORD=${MINIO_ROOT_PASSWORD:?error}
         # https://min.io/docs/minio/linux/reference/minio-server/settings/root-credentials.html#root-user
-      - MINIO_ROOT_USER=${MINIO_TEST_ROOT_USER:?error}
+      - MINIO_ROOT_USER=${MINIO_ROOT_USER:?error}
     # https://docs.docker.com/reference/compose-file/services/#command
     command: server /data --console-address ":9001"
     # https://docs.docker.com/reference/dockerfile/#healthcheck
@@ -69,21 +69,16 @@ services:
       - minio_test
     # https://docs.docker.com/reference/compose-file/services/#restart
     restart: unless-stopped
-    # https://docs.docker.com/reference/compose-file/services/#volumes
-    volumes:
-      - source: minio_test_data
-        target: /data
-        type: volume
-  postgres_test:
+  postgres-test:
     # https://docs.docker.com/compose/environment-variables/
     # https://docs.docker.com/reference/compose-file/services/#environment
     environment:
         # https://github.com/docker-library/docs/blob/master/postgres/README.md#postgres_db
-      - POSTGRES_DB=${POSTGRES_TEST_DB:?error}
+      - POSTGRES_DB=${POSTGRES_DB:?error}
         # https://github.com/docker-library/docs/blob/master/postgres/README.md#postgres_password
-      - POSTGRES_PASSWORD=${POSTGRES_TEST_PASSWORD:?error}
+      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:?error}
         # https://github.com/docker-library/docs/blob/master/postgres/README.md#postgres_user
-      - POSTGRES_USER=${POSTGRES_TEST_USER:?error}
+      - POSTGRES_USER=${POSTGRES_USER:?error}
     # https://docs.docker.com/reference/dockerfile/#healthcheck
     # https://docs.docker.com/reference/compose-file/services/#healthcheck
     healthcheck:
@@ -105,13 +100,4 @@ services:
     profiles:
       - postgres_test
     # https://docs.docker.com/reference/compose-file/services/#restart
-    restart: unless-stopped
-    # https://docs.docker.com/reference/compose-file/services/#volumes
-    volumes:
-      - source: postgres_test_data
-        target: /var/lib/postgresql/data
-        type: volume
-# https://docs.docker.com/reference/compose-file/volumes/
-volumes:
-  minio_test_data:
-  postgres_test_data:
+    restart: unless-stopped