Table of Contents:
In order to begin development you must do the following:
- If developing on a Mac make sure you have xcode command line tools installed. Use the following if they are not:
xcode-select --install
- Command line tools are used for access to the
makecommand line tool. Make is currently being used solely as a proxy for running the scripts located in thebin/directory of this project. If you do not havemakeinstalled you can run the appropriate scripts in thebin/directory instead.
- Command line tools are used for access to the
- Clone this repository
git clone git@github.com:jerkeeler/tim_keeler.git
- Create the logs directory and provide it correct permissions
mkdir /var/log/timkeeler chown youruser:yourgroup /var/log/timkeeler
- Install python >= 3.7 using installation method of your choice, I would suggest pyenv
- Install virtualenv in your new python environment
- Create a new virtualenv in this directory and activate it:
python -m virtualenv .venv source .venv/bin/activate - Install nodejs and then install yarn using npm
npm install -g yarn
- Now install all requirements for this project by running the following:
make requirements # OR ./bin/make_requirements - Create a
tim_keeler/confg/settings.tomlfile and fill in the settings with values (see configs section for requireed config values and example file structure) - Run the Django migrations
./manage.py migrate
- At this point you should be setup and able to run and develop the website locally. Run the following commands then visit localhost:8000 to view the site.
./manage.py runserver
Luckily for you, deploying has been made easy using Fabric. All you need to do to deploy is to get an account on the host box, create tim_keeler/conf/remote.toml and fill it in with the required values (see configs section for example file). Once that is setup you can run the following commands whenever you want to deploy. Note that the remote box will always pull from the master branch so make sure you have committed any changes, merged to master, and pushed to origin before deploying.
All commands for deploying are located in the fabfile.py file. To run any of the commands prefix them with fab. If we want to run the "example" command we would run the following from our command line: fab example. Below is the list of commands that exist in the fabfile with brief descriptions of what each one does:
Usage:
fab deployThis command will deploy the master branch to the remote host.
IMPORTANT: You must also be on the master branch locally(!) otherwise there is a chance that you will deploy static files (js, css) that are not on the master branch. There should eventually be a check in the fabfile that prevents this.
The command does the following:
- Runs
make buildlocally - Tarballs the
dist/directory locally - On the remote host runs
git pull,pip install, and./manage.py migrate - Copies over the tarball to the remote host and unpacks into the
dist/directory there - Restarts all services
- Cleans up tarball
Usage:
fab download_log <log_name>Downloads the requested log file to /tmp/<log_name>.log. log_name should be either "info" or "error"
Usage:
fab logs <log_name>Downloads the request log file locally then runs less on the logs so that you can view them. After you exit less it will clean up the log files. In essence it's a way to view the log files without having to log into the box.
Usage:
fab hostnameRuns the hostname command on the remote host. Used for testing.
[app]
allowed_hosts = [
"*",
]
debug = true
environment = "DEV"
name = "timkeeler.net"
secret_key = "youmustchangethisvalue"
[db]
name = "db"
[email]
from = "example@example.com"
host = "smtp.example.com"
password = "examplepassword"
port = 587
tls = true
username = "example"
[captcha]
secret_key = "captcha_secret_key"
site_key = "captcha_site_key"
[[admins]]
email = "admin1@example.com"
name = "admin1"
[[admins]]
email = "admin2@example.com"
name = "admin2"app_location = '/path/to/app/on/server'
gunicorn_process_name = 'process_name'
host = 'example.com'