Local env (#243)

Scripts and instructions for running the backend in a virtual env

The breaking change for devs is they have to move their `.env.dev` for `app/.env.docker` in order for their project to continue functioning.

---------

Co-authored-by: Fang Yi Liu <fangyiliu@gmail.com>

.gitignore

@@ -12,6 +12,9 @@ app/htmlcov
 
 ### dotenv ###
 .env.dev
+.env.docker
+.env.local
+.env.test
 .env
 
 ### Vim ###

app/.dockerignore

@@ -1,4 +1,4 @@
-.env.dev
+.env.docker
 .dockerignore
 Dockerfile
 app/.coverage

app/.env.docker-example

@@ -0,0 +1,40 @@
+DEBUG=1
+SECRET_KEY=foo
+DJANGO_PORT=8000
+DJANGO_ALLOWED_HOSTS="localhost 127.0.0.1 [::1]"
+DJANGO_SUPERUSER_USERNAME=admin1111
+DJANGO_SUPERUSER_EMAIL=admin@admin.com
+DJANGO_SUPERUSER_PASSWORD=admin
+
+# postgres settings for docker
+SQL_ENGINE=django.db.backends.postgresql
+SQL_DATABASE=people_depot_dev
+SQL_USER=people_depot
+SQL_PASSWORD=people_depot
+SQL_HOST=db
+SQL_PORT=5432
+DATABASE=postgres
+
+# postgres settings for local development
+# SQL_ENGINE=django.db.backends.postgresql
+# SQL_DATABASE=postgres
+# SQL_USER=
+# SQL_PASSWORD=
+# SQL_HOST=localhost
+# SQL_PORT=5432
+# DATABASE=postgres
+
+# sqlite settings for local development
+# SQL_ENGINE=
+# SQL_DATABASE=
+# SQL_USER=
+# SQL_PASSWORD=
+# SQL_HOST=
+# SQL_PORT=
+# DATABASE=
+
+COGNITO_DOMAIN=peopledepot
+COGNITO_AWS_REGION=us-west-2
+COGNITO_USER_POOL=us-west-2_Fn4rkZpuB
+
+PEOPLE_DEPOT_API_SECRET=people-depot-api-secret

app/Dockerfile

@@ -21,7 +21,6 @@ RUN \
   && apt-get install --no-install-recommends -yqq \
   netcat=1.10-46 \
   gcc=4:10.2.1-1 \
-  postgresql=13+225+deb11u1 \
   graphviz=2.42.2-5
 
 # install dependencies

app/core/models.py

@@ -48,14 +48,16 @@ class User(PermissionsMixin, AbstractBaseUser, AbstractBaseModel):
     # Common fields #
     # For cognito-users username will contain `sub` claim from jwt token
     # (unique identifier (UUID) for the authenticated user).
-    # For django-users it will contain username which will be used to login into django-admin site
+    # For django-users it will contain username which will be used to login
+    # into django-admin site
     username = models.CharField(
         "Username", max_length=255, unique=True, validators=[username_validator]
     )
     is_active = models.BooleanField("Active", default=True)
 
     # Cognito-user related fields #
-    # some additional fields which will be filled-out only for users registered via Cognito
+    # some additional fields which will be filled-out only for users
+    # registered via Cognito
     pass
 
     # Django-user related fields #
@@ -83,7 +85,8 @@ class User(PermissionsMixin, AbstractBaseUser, AbstractBaseModel):
 
     # desired_roles = models.ManyToManyField("Role")
     # availability = models.IntegerField()  # not in ERD, is a separate table. Want to confirm to remove this
-    # referred_by = models.ForeignKey(referrer, on_delete=models.PROTECT) # FK to referrer
+    # referred_by = models.ForeignKey(referrer, on_delete=models.PROTECT) # FK
+    # to referrer
 
     linkedin_account = models.CharField(max_length=255, blank=True)
     github_handle = models.CharField(max_length=255, blank=True)
@@ -94,7 +97,8 @@ class User(PermissionsMixin, AbstractBaseUser, AbstractBaseModel):
     texting_ok = models.BooleanField(default=True)
 
     time_zone = TimeZoneField(blank=True, use_pytz=False, default="America/Los_Angeles")
-    # conduct = models.BooleanField()  # not in ERD. Maybe we should remove this
+    # conduct = models.BooleanField()  # not in ERD. Maybe we should remove
+    # this
 
     objects = UserManager()
 

app/core/tests/test_api.py

@@ -26,7 +26,8 @@
 CREATE_USER_PAYLOAD = {
     "username": "TestUserAPI",
     "password": "testpass",
-    # time_zone is required because django_timezone_field doesn't yet support the blank string
+    # time_zone is required because django_timezone_field doesn't yet support
+    # the blank string
     "time_zone": "America/Los_Angeles",
 }
 

docker-compose.yml

@@ -9,7 +9,7 @@ services:
     ports:
       - 8000:8000
     env_file:
-      - ./.env.dev
+      - ./app/.env.docker
     depends_on:
       - db
   db:
@@ -20,6 +20,8 @@ services:
       - POSTGRES_USER=people_depot
       - POSTGRES_PASSWORD=people_depot
       - POSTGRES_DB=people_depot_dev
+    ports:
+      - 5432:5432
   mkdocs:
     image: hackforlaops/mkdocs:latest
     command: mkdocs serve --dev-addr 0.0.0.0:8000

docs/how-to/run-local.md

@@ -0,0 +1,42 @@
+# Run backend in venv
+
+If you have a requirement to run on your local machine or you are unable to get it to work on
+Docker, do the following steps.  WARNING: If you run into issues you will get limited support.
+
+Run these commands from the `app` directory:
+
+1. Copy `.env.docker-example` to `.env.local`
+1. Inspect `.env.local` and change values as appropriate.  The file includes instructions on how to use local `postgres` and  `sqlite` for the database. `sqlite` has no set up.  It uses a file `db.sqlite3`.  If it is not there, it automatically creates it.
+1. **Mac only**: If you have a Mac, the python command may not be found and scripts will fail.  Try to run python using the "python" command from the terminal.  If you get an error that the python command is
+    not found, type: `alias python="python3"`
+1. Run these commands from the terminal in the project root.
+
+```bash
+cd app
+
+# copy the env file
+cp .env.docker-example .env.local
+
+# create a virtual environment
+python -m venv venv
+
+# activate (enter) the virtual environment
+source venv/bin/activate
+# install dependencies
+pip install -r requirements.txt
+
+# start local server
+../scripts/start-local.sh
+# start server with alternate port
+# DJANGO_PORT=8001 ../scripts/start-local.sh
+
+# browse to http://localhost:8000 (or 8001) to see the app
+
+# Ctrl-C to stop the server
+
+# deactivate (exit) the virtual environment
+# to return to the system global environment
+deactivate
+```
+
+**TIP**: Look up `direnv` for a useful method to automatically enter and exit virtual environments based on the current directory.

scripts/createsuperuser.sh

@@ -8,5 +8,5 @@ set -x
 
 # This command requires the DJANGO_SUPERUSER_USERNAME and
 # DJANGO_SUPERUSER_PASSWORD environmental variables to be set when django starts
-
+echo "DJANGO_SUPERUSER_USERNAME: $DJANGO_SUPERUSER_USERNAME"
 docker-compose exec web python manage.py createsuperuser --no-input

scripts/loadenv.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+echo SQL USER "$SQL_USER"
+export file=$1
+echo "file = $file / $1 / $2"
+if [ "$file" == "" ]
+then
+  echo "File not specified.  Using .env.local"
+  file=".env.local"
+fi
+
+echo "Loading environment variables from $file"
+
+if [ ! -f "$file" ]
+then
+  echo "File $file not found"
+  echo "If executing locally, copy .env.example.dev to $file and edit as needed"
+  return 1
+fi
+while IFS= read -r line; do
+  if [[ -n "$line" ]]; then
+    export export_command="export $line"
+    echo "export_command = $export_command"
+    eval "$export_command"
+  fi
+done < <(grep -v '^#' "$file")
+echo Super user "$DJANGO_SUPERUSER_USERNAME"
+echo SQL USER "$SQL_USER"

scripts/start-local.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# Called by start-dev.sh and start-docker.sh, which sets
+#    - DATABASE_HOST
+#    - DJANGO_SUPERUSER
+#    - DJANGO_SUPERUSER_PASSWORD
+#    - DJANGO_SUPERUSER_EMAIL
+if [[ $PWD != *"app"* ]]; then
+    cd app || {
+        echo "ERROR: cd app failed"
+        return 1
+    }
+fi
+
+SCRIPT_DIR="$(dirname "$0")"
+"$SCRIPT_DIR"/loadenv.sh || {
+    echo "ERROR: loadenv.sh failed"
+    return 1
+}
+echo Admin user = "$DJANGO_SUPERUSER" email = "$DJANGO_SUPERUSER_EMAIL"
+if [[ $1 != "" ]]; then
+    port=$1
+elif [[ "$DJANGO_PORT" != "" ]]; then
+    port=$DJANGO_PORT
+else
+    port=8000
+fi
+echo Port is "$port"
+
+echo
+echo --- Executing python manage.py makemigrations ---
+echo
+python manage.py makemigrations || {
+    echo "ERROR: python manage.py makemigrations failed"
+    return 1
+}
+
+
+echo
+echo --- Executing python manage.py migrate ---
+echo
+python manage.py migrate || {
+    echo "ERROR: python manage.py migrate failed"
+    return 1
+}
+
+echo
+echo --- Executing python manage.py shell to check if "$DJANGO_SUPERUSER_USERNAME" exists
+echo
+python manage.py shell -c "from core.models import User; exists = (User.objects.filter(username='$DJANGO_SUPERUSER_USERNAME').exists()); sys.exit(0 if exists else 1)"
+
+superuser_exists=$?
+
+if [ $superuser_exists -eq 1 ]; then
+  echo
+  echo --- Executing python manage.py createsuperuser ---
+  echo
+  if ! python manage.py createsuperuser --username "$DJANGO_SUPERUSER_USERNAME" --email "$DJANGO_SUPERUSER_EMAIL" --no-input;
+  then
+    echo "ERROR: python manage.py createsuperuser failed"
+    return 1
+  fi
+else
+  echo --- INFO: Skipping python manage.py createsuperuser - super user "$DJANGO_SUPERUSER_USERNAME" already exists.
+fi
+
+echo
+echo --- All prep steps successful!  Executing python manage.py runserver
+echo
+
+python manage.py runserver 0.0.0.0:"$port"