- Ubuntu
- Django 2
- Python 3 with
pipavailable - Apache 2.4 with
mod_wsgiandmod_ssl
All of the configuration files expect the project code to live at
/var/django/caesar.
We use Vagrant and VirtualBox to run Caesar in a virtual machine on your laptop. Here are the steps:
Clone this repository from github, if you haven't already.
git clone https://github.com/uid/caesar-web.git
Install Vagrant and VirtualBox on your laptop.
Make sure you're in your caesar-web folder, which has the Vagrantfile in it. Start the VM:
cd caesar-web
vagrant up
Ignore the final warning from apache2: Could not reliably determine the server's fully qualified domain name.
Log into it:
vagrant ssh
If it asks you for a password, the password for the vagrant account is just "vagrant".
Copy the template for settings_local.py:
cd /var/django/caesar
cp settings_local.py.template settings_local.py
The default settings are intended for development: DEBUG is turned on, a local sqlite database file is used for storing data.
Collect the static files (CSS, Javascript, images, etc.) from all the apps and libraries used by Caesar into one place where Apache can serve them (the folder apache/collectedstatic/)
./manage.py collectstatic --link
The --link option uses symlinking instead of copying; this is a good idea because it eliminates the risk that you accidentally edit the CSS or JS file in apache/collectedstatic/ rather than its original source in review/static/.
Symlinking means editing either place will modify the original.
Now, initialize the database. With the default settings_local.py file, the database is stored in a .sqlite3 file in /home/vagrant, so you can always delete that file and start this part over if things go wrong.
cd /var/django/caesar
./manage.py migrate
If you want to preload the database with test data do this:
./manage.py loaddata fixtures/test_fixtures.json
If you did NOT complete the previous step (preloading the database with test data), create a superuser that will allow you to log in to Caesar with admin privileges:
./manage.py createsuperuser
Restart the Apache webserver:
sudo apachectl graceful # to restart Apache and force it to reload Caesar
Browse to 10.18.6.31 on your laptop and try to log in, either using the superuser account you created above, or (if you're at MIT) with your MIT certificate. If login is successful, clicking on the "view all users" link at the top of the page should show you all the users in the test database.
To edit code, work with git, and use other dev tools, just work with the caesar-web folder that you checked out to your laptop. This folder tree is synced automatically with /var/django/caesar in the VM. You don't have to go inside the VM.
The only thing you do have to do from the VM is touch wsgi.py whenever you edit a Python source file and want Caesar to restart:
touch wsgi.py # can be done either from your laptop or from within vagrant ssh
The Django debug toolbar ("DjDt") appears on the right side of Caesar's web pages whenever you have DEBUG=True in settings_local.py. The toolbar is particularly useful for viewing debug messages. To print messages, use
import logging
logging.debug("hello, world")
Messages like this will appear in the Logging pane of the debug toolbar.
To run Caesar in debug mode, use the following command: python -m pdb manage.py runserver localhost:8888
This will cause Django to automatically reload all altered code. Additionally, by using: import pdb; pdb.set_trace() you can drop down into a PDB session, which is incredibly useful for debugging crashes & bugs.
By default, your development web server isn't visible outside your laptop. Nobody else can browse to 10.18.6.31. But you can make it visible (at your laptop's IP address) using an ssh tunnel:
sudo ssh -L 0.0.0.0:80:localhost:80 -L 0.0.0.0:443:localhost:443 vagrant@10.18.6.31
(Default) Password: vagrant
These instructions were written for deployment on Ubuntu 14 (Trusty) with Apache 2.4.
Caesar assumes that it will live at /var/django/caesar, so create that folder and give yourself ownership of it:
sudo mkdir -p /var/django/caesar
sudo chown $USER /var/django/caesar
sudo chgrp $USER /var/django/caesar
Now check out the code:
sudo apt-get install -y git # make sure git is installed
git clone https://github.com/uid/caesar-web.git /var/django/caesar
Now run the setup script:
sudo /var/django/caesar/setup.sh
You will need to create a MySql database to run a deployed instance of Caesar. Either install MySql locally, or make a database on some hosted MySql service.
Make sure your MySql database has its default character set configured to utf8mb4.
It's easiest to do it while the database is still fresh and empty.
Use the mysql client to visit your database, and run this command:
alter database character set utf8mb4;
To point Caesar to the right database, copy the local settings file:
cd /var/django/caesar
cp settings_local.py.template settings_local.py
Then edit settings_local.py and change the settings appropriately.
Collect the static files (CSS, Javascript, images, etc.) from all the apps and libraries used by Caesar into one place where Apache can serve them:
./manage.py collectstatic --link
Finally, if you are starting a new database, the database needs some setup:
cd /var/django/caesar
./manage.py migrate
./manage.py createsuperuser
sudo apachectl graceful # restart Apache
Finally browse to your web server and try to log in.
Set up SSL access by obtaining certificates for your server hostname. For CSAIL, the instructions are here:
https://tig.csail.mit.edu/web-services/server-certificates/
Create an ssl/ subfolder inside /var/django/caesar/apache, and make it readable only by the ubuntu user.
Put these files in it:
mitCAclient.pem
caesar.eecs.mit.edu-full-chain.crt
caesar.eecs.mit.edu.key
caesar.eecs.mit.edu.crt
The CA file is MIT's certificate authority certificate.
The .key file is the private key file that you created when you ran openssl.
It should start with a line BEGIN RSA PRIVATE KEY and end with a line END RSA PRIVATE KEY.
The .crt file is the "X509 Certificate only, Base64 encoded" version of the certificate you got back from the certificate-request process.
It should have a single certificate block in it, bounded by BEGIN CERTIFICATE and END CERTIFICATE lines.
The full-chain.crt file is the "X509 Intermediates/root only, Base64 encoded" link you got back from the process.
It should have multiple certificate blocks in it, each bounded by BEGIN CERTIFICATE and END CERTIFICATE lines.
Edit the /var/django/caesar/apache/caesar.conf file so that ServerName is the fully-qualified hostname in your certificates, and so that the paths in the SSL...File settings point correctly to the files above.
Restart Apache with sudo apachectl graceful.
If you are using MySql, you need to make sure that the files and comments tables in the database are using the utf8mb4 character set. Otherwise you will not be able to have Unicode characters and emojis in source code files or reviewing comments.
To check what the default character set is, use the mysql client to visit your database, and run these commands:
show variables where variable_name = 'character_set_database';
show full columns from files;
show full columns from comments;
If you see utf8mb4 or utf8mb4_general_ci for all appropriate character set and collations, then it's correctly configured.
If you see latin1 or some other character set, your database isn't using Unicode.
To fix the database default:
alter database character set utf8mb4;
To fix the tables:
alter table files convert to character set utf8mb4;
alter table comments convert to character set utf8mb4;
To download Caesar's database into a file (in a Unicode-safe way):
mysqldump --skip-extended-insert -q --default-character-set=utf8mb4 --host=HOST --user=USER --password=PASSWORD NAME -r caesar-`date '+%Y-%m-%d'`.sql
Replace HOST, USER, PASSWORD, and NAME with their corresponding values in settings_local.py.
To restore a backup to MySql, first start the mysql client:
mysql --host=HOST --user=USER --password=PASSWORD --database=NAME
and then at its prompt:
set names 'utf8mb4';
source caesar-YYYY-MM-DD.sql
where caesar-YYYY-MM-DD.sql is the backup file you want to restore.
The backup can also be restored into a Sqlite3 database for use in development, by first translating it with mysql2sqlite, and then importing it:
mysql2sqlite caesar-YYYY-MM-DD.sql > sqlite3.sql
sqlite3 /var/django/db/caesar.sqlite3
.read sqlite3.sql
.quit