revise README

Author: forrestbao

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,60 @@ 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 starting CodePod, you will also need to initialize the database.  See [below](#initializing-the-database).
+If the database has been updated (you can tell by some errors) since you last pulled the code, you will need to update the database. See [below](#updating-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 the database 
+
+To initialize the database, 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
+  ```
 
-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:
+and then **from the shell of the API container** run:
 
 ```bash
-npx prisma migrate dev
+npx prisma migrate deploy
 ```
 
-This command is also needed after the database schema is changed. The protocol is:
+### Updating the database
 
-- 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.
+If the schema has been updated since you last pulled the code (you will most likely observe database-related issues), you will need to update the database. 
+To do that, enter the shell of 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
+ 
+  ```bash
+  npx prisma migrate dev
+  ``` 
+
+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 +154,20 @@ cd ./api/
 # Run 'npm install' instead if you are using npm
 yarn
 ```
+
+
+# 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}
+}
+```