README.md

HomeNet

Apartment rental listing platform to match realtors with potential home renters and buyers.

• https://pushforward.nyc
• https://pushforward.nyc/admin

Services:

• Hosting: https://my.vultr.com
• Payments: https://dashboard.stripe.com/account/team + https://plaid.com/docs/
• Emails: https://app.mailgun.com/app/account/settings
• DNS / CDN: https://dash.cloudflare.com/413ad3842c5a82a780b582d8de8dc903/zalad.io/dns
• Maps: https://account.mapbox.com/auth/signin/?route-to=%22/access-tokens/%22 + https://console.cloud.google.com/google/maps-apis/overview?pli=1&project=pennybags-1556050514027

Project Quickstart

---

0. Clone the repository

Clone this repo into the /opt directory:

# Use ssh (not https) to avoid push permission errors
# (replace YOUR_GITHUB_USER with your github username)
git clone [email protected]:YOUR_GITHUB_USER/homenet.git /opt/monadical.homenet

If you clone it elsewhere instead (e.g. inside your home folder), you must symlink /opt/monadical.homenet to the repo location:

ln -s /path/to/cloned/repo/homenet /opt/monadical.homenet
ln -s /opt/monadical.homenet /opt/homenet

---

1. Install the dependencies

Make the JS and Python dependencies accessible from your $PATH

If you use Bash, add these lines to your ~/.bashrc or ~/.bash_profile file:

PATH="$PATH:./.venv/bin:./../.venv/bin:./node_modules/.bin"
PIPENV_VENV_IN_PROJECT=1
PIPENV_IGNORE_VIRTUALENVS=1

If you use Fish, add these lines to your ~/.config/fish/config.fish file:

set -x PATH $PATH ./node_modules/.bin ./.venv/bin ./../.venv/bin
set -x PIPENV_VENV_IN_PROJECT 1
set -x PIPENV_IGNORE_VIRTUALENVS 1

Python dependencies

Install Python >= 3.7.4

sudo apt install python3.7 python3-pip python3.7-dev libpango1.0-0  # or `brew install python3 pango`

Optional: You can also use pyenv to install python3.7 if you have trouble installing it with apt or brew.

Install the pipenv package manager

python3.7 -m pip install pipenv

Install the project Python dependencies

(The Python dependencies are defined in ./Pipfile)

cd /opt/monadical.homenet
pipenv install --dev
pipenv clean
pipenv lock --clear
pipenv check

Javascript dependencies (dev machines only):

Install Node >= 12.6.0

On Ubuntu:

sudo apt install npm gdal-bin

On Mac:

brew install node gdal

Install the yarn package manager

npm install --global npm
npm install --upgrade --global yarn

Install the project JS dependencies

(The JS dependencies are defined in ./pennydjango/js/package.json)

cd /opt/monadical.homenet/pennydjango/js
yarn install

---

2. Setup the system environment

Point homenet.l domain traffic to localhost

Add this line to your /etc/hosts file (sudo is required to edit it):

127.0.0.1   homenet.l

Install supervisord

Supervisord is used to manage starting and stopping nginx, postgresql, and any other background services.

On Ubuntu:

sudo apt install supervisor
systemctl enable supervisor

On Mac:

brew install supervisor
brew services start supervisor

---

3. Setup Postgresql

Install the latest Postgresl version

On Ubuntu:

sudo echo "deb http://apt.postgresql.org/pub/repos/apt/ bionic-pgdg main" >> /etc/apt/sources.list
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update
sudo apt install postgresql libpq-dev

# Postgresl is managed by supervisord, so we dont want it being started at boot
systemctl stop postgresql
systemctl disable postgresql

On macOS:

brew install postgresql
brew link --overwrite --force postgresql

# Postgresl is managed by supervisord, so we dont want it being started at boot
brew services stop postgresql

Instantiate the pennybags database

cd /opt/monadical.homenet

# instantiate a new postgresql db data dir
initdb data/database

# Create role, db, and grant privileges
pg_ctl -D data/database start
psql -c "CREATE USER penny WITH PASSWORD 'penny';" postgres
psql -c "CREATE DATABASE penny OWNER penny;" postgres
psql -c "GRANT ALL PRIVILEGES ON DATABASE penny TO penny;" postgres
psql -c "ALTER USER penny CREATEDB;" postgres
pg_ctl -D data/database stop

Run the initial migrations

cd /opt/monadical.homenet

# Run the initial db migrations
pg_ctl -D data/database start
./.venv/bin/python ./pennydjango/manage.py migrate
pg_ctl -D data/database stop

---

4. Setup the Nginx webserver

Install the latest Nginx version

On Ubuntu:

sudo add-apt-repository -y ppa:nginx/stable
sudo apt update
sudo apt install nginx
systemctl stop nginx
systemctl disable nginx

On macOS:

brew install nginx
brew services stop nginx

Generate a self-signed SSL certificate

cd /opt/monadical.homenet
./bin/generate_dev_ssl homenet.l openssl
./bin/generate_dev_ssl homenet.zalad.io openssl
# optionally specify mkcert arg instead of openssl if its installed
# https://github.com/FiloSottile/mkcert

---

5. Run the development server

Start Postgresql and Nginx

Background processes are managed by Supervisord, they must be started in order for Django to work.

First, link the supervisord config to your system supervisord config folder.

On Ubuntu:

ln -s /opt/monadical.homenet/etc/supervisor/monadical.homenet.dev.ubuntu.conf /etc/supervisor/conf.d/

On macOS:

mkdir /usr/local/etc/supervisor.d
ln -s /opt/monadical.homenet/etc/supervisor/monadical.homenet.dev.ubuntu.conf /usr/local/etc/supervisor.d/

Then start supervisord and confirm the background tasks have been started succesfully.

supervisorctl reread
supervisorctl update
supervisorctl status

Should output something like:

monadical.homenet:nginx          RUNNING   pid 28518, uptime 0:25:32
monadical.homenet:django         RUNNING   pid 28517, uptime 0:25:32
monadical.homenet:postgres       RUNNING   pid 28516, uptime 0:25:32

If you encounter any problems, you can check the logs here:
/opt/monadical.homenet/data/logs/*.log

Start Django Runserver

cd /opt/monadical.homenet

# activate the virtualenv
pipenv shell
# or source .venb/bin/activate       (in bash)
# or source .venv/bin/activate.fish  (in fish)

# Start the django runserver
./manage.py runserver

✅ Then open https://homenet.l in your browser.

Alternatively, open http://127.0.0.1:8000 to access runserver directly without using nginx (always use nginx if possible though).

---

Common Tasks

Activate the Python Virtualenv

cd /opt/monadical.homenet
source .venv/bin/activate
# or `source .venv/bin/activate.fish`
# or `pipenv shell`

Rebuild Javascript Pages

cd /opt/monadical.homenet/pennydjango/js
webpack --display-error-details
git add ../static/pages
git commit -m "rebuilt staticfiles"

Deploy changes to a server

# ssh into the server running django. e.g.
ssh -p 44 [email protected]
cd /opt/monadical.homenet

# make a database backup to be safe
pg_dump --user=penny penny > data/backups/penny_2020-02-14.sql

# stop the server
supervisorctl stop all

# pull the latest codebase version
git pull

# update any python dependencies
pipenv install

# run the database migrations
pipenv shell
./manage.py migrate

# restart the server, then confirm it's all working as expected
supervisorctl start all

Start/stop/restart Nginx, Django, Postgresql

cd /opt/monadical.homenet

# make sure supervisord is running first
systemctl start supervisor  # on mac: brew services start supervisor

# then check the status of all services or a specific service
supervisorctl status <service|all>
supervisorctl stop <service|all>
supervisorctl start <service|all>

# to restart django for example
supervisorctl restart monadical.homenet:penny-django

Inspect Logfile Output

cd /opt/monadical.homenet/data/logs
tail -f nginx.err
tail -f nginx.out
tail -f postgres.log
tail -f reloads.log
tail -f django.log
# etc.

Run Tests

cd /opt/monadical.homenet
source .venv/bin/activate

# Run the django management test command
./manage.py test

Run Migrations

# first make sure postgresql is running with supervisord

cd /opt/monadical.homenet/pennydjango
# activate virtualenv (see above)

./manage.py migrate

Update an API Secret

# ssh into the machine running django, e.g.
ssh -p 44 [email protected]

# then locate the project directory and env secrets file
cd /opt/monadical.homenet
nano env/secrets.env

# then restart django for the changes to take effect (see above)
supversiorctl restart monadical.homenet:penny-django

---

Troubleshooting

Check the installed binary versions

python3 --version       # should be >= 3.7.3, check inside virtualenv too
pipenv --version        # should be >= 2018.11.26

node --version          # should be >= 12.6.0
npm --version           # should be >= 6.10.2
yarn --version          # should be >= 1.17.3

supervisord --version   # should be >= 3.3.5
postgres --version      # should be >= 10.0
nginx --version         # should be >= 1.15.12      

Check the installed binary locations

which <binary>      # e.g. `which nginx` or `which python3`

Yarn install/locking failures

Clear the yarn cache and try again.

yarn cache clean
yarn install

Pipenv install/locking failures

Clear the pipenv cache and try again.

pipenv lock --clear
pipenv clean
pipenv install