Merge pull request #334 from forrestbao/main

forrestbao · web-flow · commit e3eebe746a55 · 2023-06-19T22:06:50.000-05:00
revise README
diff --git a/README.md b/README.md
@@ -24,22 +24,6 @@ plugin](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vsco
 to format your code before checking in. 
 Last but not least, give us a star on Github! 
 
-# Citation
-
-https://arxiv.org/abs/2301.02410
-
-```
-@misc{https://doi.org/10.48550/arxiv.2301.02410,
-  doi = {10.48550/ARXIV.2301.02410},
-  url = {https://arxiv.org/abs/2301.02410},
-  author = {Li, Hebi and Bao, Forrest Sheng and Xiao, Qi and Tian, Jin},
-  title = {Codepod: A Namespace-Aware, Hierarchical Jupyter for Interactive Development at Scale},
-  publisher = {arXiv},
-  year = {2023},
-  copyright = {Creative Commons Attribution 4.0 International}
-}
-```
-
 # Gallery 
 
 Thanks to our community, we now have CodePod showcases ranging from analytical geometry to bioinformatics. 
@@ -50,23 +34,47 @@ Thanks to our community, we now have CodePod showcases ranging from analytical g
 
 # Developing CodePod using docker-compose
 
-The docker compose files are in `compose/dev` folder. The `dev` stack mounts the
+First clone CodePod: 
+
+```bash
+git clone https://github.com/codepod-io/codepod.git
+```
+
+We use the variable `CODEPOD_ROOT` to refer to the root folder of the CodePod. 
+If you just ran the command above, then `CODEPOD_ROOT` is the folder you just cloned.
+
+Now enter the `CODEPOD_ROOT/compose` folder: 
+
+```bash
+cd codepod/compose
+```
+
+The docker compose files are in `CODEPOD_ROOT/compose/dev` folder. The `dev` stack mounts the
 `src` folder, so that you can edit the files on your local computer, and let the
 node.js process inside the container do the compiling and hot-reloading.
 
 To install docker-compose, follow the official [Docker documentation](https://docs.docker.com/compose/install/linux/).
 
 ## .env file
 
-First, create a `dev/.env` file with the following content (leave as is or change the value to
+Now enter the `CODEPOD_ROOT/compose/dev` folder 
+
+
+```bash
+cd dev
+```
+
+and create a `.env` file with the following content (leave as is or change the value to
 whatever you want).
 
 ```properties
+# Mandatory settings
 POSTGRES_USER=myusername
 POSTGRES_PASSWORD=mypassword
 POSTGRES_DB=mydbname
 JWT_SECRET=mysupersecretjwttoken
 
+# optional settings
 GOOGLE_CLIENT_ID=<google oauth client id>
 
 EXPORT_AWS_S3_REGION=us-west-1
@@ -80,37 +88,59 @@ Optional:
 - Leave the `GOOGLE_CLIENT_ID` empty if you do not need the OAuth provided by Google.
 - `EXPORT_AWS_S3_XXX` are used for file export. You could leave it empty if you don't use it.
 
-## Start the stack
+## Starting the stack
+
+From the `CODEPOD_ROOT/compose/dev` folder, run:
 
 ```bash
-cd dev
 docker compose up -d
 ```
 
-You need to initialized the database first before starting the stack. See below.
+If you this is your first time setting up CodePod, or the database schema has been updated (which you can tell from errors), you will also need to [initalize database tables](#initializing-the-database).
 
 Wait a few minutes for the package installation and compilation. Once the `ui` and
 `api` containers are ready, go to `http://localhost:80` to see the app.
 
 - `http://localhost:80/graphql`: Apollo GraphQL explorer for the backend APIs
 - `http://prisma.127.0.0.1.sslip.io`: Prisma Studio for viewing and debugging the database.
 
-## Initialize the database
+### Initializing database tables
+
+To initialize or update the database schema, open a shell into the API container (by default called `dev-api-1` but please use `docker ps` to confirm): 
+  
+  ```bash
+  docker exec -it dev-api-1 /bin/bash
+  ```
+
+and then **from the shell of the API container** run:
 
-If this is your first time running it, you would need to initialize the database as it's empty. To do that, open a shell into the API container and run:
 
-```bash
-npx prisma migrate dev
-```
 
-This command is also needed after the database schema is changed. The protocol is:
+> Known issues: if you get the error below during the migration, 
+> 
+> ```bash
+> EACCES: permission denied, unlink '/app/node_modules/.prisma/client/index.js'
+> EACCES: permission denied, unlink '/app/node_modules/.prisma/client/index.js'
+> ```
+> then please change the ownership of the folder `node_modules` (**from the shell of the API container**):
+> ```bash
+> chown node:node node_modules/ -R
+> ```
+> Afterwards, re-run 
+> ```bash
+> npx prisma migrate dev
+> ```
 
-- One developer changed [the schema](./api/prisma/schema.prisma). He will run
-  `npx prisma migrate dev --name add_a_new_field`. This will generate a
-  migration, e.g. [this
-  migration](./api/prisma/migrations/20221206194247_add_google_login/migration.sql).
-  The schema change along with this migration need to be checked in to git.
-- Another developer pulls the change, then running the `npx prisma migrate dev` (in the api container's shell) to apply the schema change.
+### Preparing for database migration
+
+If you are a developer who wants to change the database schema for adding a feature, you can update the schema file `CODEPOD_ROOT/api/prisma/schema.prisma` and then run 
+
+  ```bash
+  npx prisma migrate dev --name add_a_new_field
+  ```
+
+to generate a migration, like [this](./api/prisma/migrations/20221206194247_add_google_login/migration.sql).
+The schema change along with this migration need to be checked in (add, commit, and push) to git.
 
 ## Auto-completion & Linting
 
@@ -123,3 +153,60 @@ cd ./api/
 # Run 'npm install' instead if you are using npm
 yarn
 ```
+
+## Starting two stacks simultaneously
+
+It might be necessary to create two Docker stacks for two verions of CodePod, respectively. For example, you might want to test the new version of CodePod while keeping the old version running.
+
+Because Docker uses the folder name as the default suffix in container names, these two stacks may conflict with each other. To avoid this, you can use the `COMPOSE_PROJECT_NAME` environment variable to set a prefix for the container names. For example, you can set `COMPOSE_PROJECT_NAME=codepod-v2` in the `CODEPOD_ROOT/compose/dev/.env` file of the new stack, and then [start](#starting-the-stack) the new stack. 
+
+The two stacks also may share the same network ports due to the same configuration files used. To set the ports, search for the following lines in  `CODEPOD_ROOT/compose/dev/nginx.conf` (two occurences of the two lines in the file) file of the new stack:
+
+```yaml
+        listen 80; 
+        listen [::]:80;
+```
+
+and the following section in the `CODEPOD_ROOT/compose/dev/compose.yml` file of the new stack:
+
+```
+  nginx:
+    image: nginx:alpine
+    ports:
+      - 80:80
+    volumes:
+      - ./nginx.conf:/etc/nginx/conf.d/default.conf
+```
+
+and replace the default port number 80 to a new port number. For example, you can set the port number to 8080 for all occurences of 80. 
+
+Also, comment out the port section of the `ui` container in `CODEPOD_ROOT/compose/dev/compose.yml` as: 
+
+```
+  ui:
+    image: node:18
+    working_dir: /app
+#    ports:
+      # For react hot-reloading in development.
+#    - 3000:3000
+```
+
+
+Then, you can access the new stack at `http://localhost:8080`.
+
+
+# Citation
+
+https://arxiv.org/abs/2301.02410
+
+```
+@misc{https://doi.org/10.48550/arxiv.2301.02410,
+  doi = {10.48550/ARXIV.2301.02410},
+  url = {https://arxiv.org/abs/2301.02410},
+  author = {Li, Hebi and Bao, Forrest Sheng and Xiao, Qi and Tian, Jin},
+  title = {Codepod: A Namespace-Aware, Hierarchical Jupyter for Interactive Development at Scale},
+  publisher = {arXiv},
+  year = {2023},
+  copyright = {Creative Commons Attribution 4.0 International}
+}
+```
