ACCESS_TOKEN_SECRET = '???'
```
+### SSL Certificate
+
+If you wish to host your system publicly, you'll need an SSL certificate
+signed by a proper authority.
+
+If you are working on local system for development, a self signed certificate
+will suffice. There are plenty of resources available for learning how to
+create one, so that will not be detailed here. Note that the Vagrant file will
+automatically generated a self signed certificate within the virtual machine.
+
+The certificate should be installed using nginx.
+
# Development Install
If you need to setup the project for development, it is highly recommend that
1. Ensure `*.py` in `secret/` are never added to the git repo.
(.gitignore should help warn against taking this action)
-1. Install [VirtualBox](http://www.virtualbox.com/)
+1. Install [VirtualBox](http://www.virtualbox.org/)
1. Install [vagrant](http://www.vagrantup.com/) 1.3 or higher
1. Connect to the virtual machine with `vagrant ssh`
Note:
-Port 80 of the virtual machine will be configured as port 6659 on the host
+Port 443 of the virtual machine will be configured as port 6659 on the host
system. While on the host system, fire up your favorite browser and point it at
-`http://localhost:6659/`. This connects to your host system on port 6659, which
-forwards to your virtual machine's web site.
+`https://localhost:6659/`. This connects to your host system on port 6659, which
+forwards to your virtual machine's web site using SSL.
+
+Port 80 of the virtual machine will be configured as port 16659 on the host
+system. While on the host system, fire up your favorite browser and point it at
+`http://localhost:16659/`. This connects to your host system on port 16659,
+which forwards to your virtual machine's web site using plain text.
## Completing the Virtual Machine with Fabric
*Notice* Fabric might not run properly if you presently in a virtualenv.
`deactivate` prior to running fab commands.
-1. On the virtual machine, type `cd karmanotes` to get into the code repository.
+### From the Host Machine
+
+If Fabric is available on the host machine, you should be able to run Fabric
+commands directly on the host machine, pointed at the virtual machine. If
+Fabric is not available on the Host Machine, see the next section.
+
+To setup the host machine properly, see the section about
+[accessing the VM via fabric](#accessing-the-vm-via-fabric) and then return to
+this section.
+
+Assuming those steps were followed with the alias, the following instructions
+should complete the virtual machine setup:
+
+1. `cd {project_root}` on the host machine.
+
+1. type `vmfab first_deploy`.
+
+### From within the Virtual Machine
+
+If Fabric is not available on the host machine, or just for funsies, you may
+run the Fabric commands within the virtual machine.
+
+1. Connect to the virtual machine with `vagrant ssh`.
+
+1. On the virtual machine, type `cd karmanotes` to get into the code
+ repository.
1. In the code repo of the VM, type `fab -H 127.0.0.1 first_deploy`
* `pdf2htmlEX`
On a Debian system supporting Apt, this can be done with:
-
- sudo apt-get install python-pip postgresql python-virtualenv nginx \
- virtualenvwrapper git libxml2-dev p7zip-full \
- postgresql-server-dev-9.1 libxslt1-dev \
- libmemcached-dev python-dev rabbitmq-server
-
- sudo add-apt-repository ppa:coolwanglu/pdf2htmlex
- sudo apt-get install pdf2htmlex
+```
+ sudo apt-get install python-pip postgresql python-virtualenv nginx \
+ virtualenvwrapper git libxml2-dev p7zip-full libffi-dev \
+ postgresql-server-dev-9.1 libxslt1-dev \
+ libmemcached-dev python-dev rabbitmq-server \
+ cmake libpng-dev libjpeg-dev libgtk2.0-dev \
+ pkg-config libfontconfig1-dev autoconf libtool
+
+ wget http://poppler.freedesktop.org/poppler-0.24.4.tar.xz
+ tar xf poppler-0.24.4.tar.xz
+ cd poppler-0.24.4
+ ./configure --prefix=/usr --enable-xpdf-headers
+ make
+ sudo make install
+ cd ~/
+
+ git clone https://github.com/fontforge/fontforge.git
+ cd fontforge
+ ./bootstrap
+ ./configure --prefix=/usr
+ make
+ sudo make install
+ cd ~/
+
+ git clone https://github.com/charlesconnell/pdf2htmlEX.git
+ cd pdf2htmlEX
+ cmake .
+ make
+ sudo make install
+```
1. Generate a PostgreSQL database and a role with read/write permissions.
* For Debian, these instructions are helpful: https://wiki.debian.org/PostgreSql
server {
listen 80;
- # don't do virtual hosting, handle all requests regardless of header
- server_name "";
+ server_name localhost;
+ return 301 https://$host$request_uri;
+ }
+
+ server {
+ listen 443;
+ ssl on;
+ server_name localhost;
client_max_body_size 20M;
location / {
# pass traffic through to gunicorn
proxy_pass http://127.0.0.1:8000;
+ # pass HTTP(S) status through to Django
+ proxy_set_header X-Forwarded-SSL $https;
+ proxy_set_header X-Forwarded-Protocol $scheme;
+ proxy_set_header X-Forwarded-Proto $scheme;
+ # pass nginx site back to Django
+ proxy_set_header Host $http_host;
}
}
Within the virtualenv:
1. Update the Python depenencies with `pip -i {project_root}/reqs/prod.txt`
+ * If you want debugging on a production-like system:
+ 1. run `pip -i {project_root}/reqs/vmdev.txt`
+ 1. change `{project_root}/manage.py` to point at `vmdev.py`
+ instead of `prod.py`
+ 1. ensure firefox is installed on the system (such as by
+ `sudo apt-get install firefox`)
1. Setup the database with `python {project_root}/manage.py syncdb --migrate`
1. If everything went well, gunicorn should be running the website on port 8000
and nginx should be serving gunicorn on port 80.
+# Update a deployed system
+
+Once code has been updated, the running web service will need to be updated
+to stay in sync with the code.
+
+## Fabric
+
+Run the `deploy` fab command. For example:
+`fab -H 127.0.0.1 deploy`
+
+## By Hand
+
+1. pull code in from the repo with `git pull`
+1. If any Python requirements have changed, install/upgrade them:
+ `pip install -r --upgrade reqs/prod.txt`
+1. If the database has changed, update the database with:
+ `python manage.py syncdb --migrate`
+1. If any static files have changed, synchornize them with;
+ `python manage.py collectstatic`
+1. Django will probably need a restart.
+ * For a dev system, ctrl-c the running process and restart it.
+ * For a production system, there are two options.
+ * `python manage.py restart_supervisord` if far reaching changes
+ have been made (that might effect celery, beat, etc)
+ * `python manage.py restart_gunicorn` if only minor Django changes
+ have been made
+ * If you are uncertain, best bet is to restart supervisord.
+
# Accessing the Vagrant Virtual Machine
+## Accessing the VM via Fabric
+If you have Fabric on the host machine, you can configure your host machine
+to run Fabric against the virtual machine.
+
+You will need to setup the host machine with the proper SSH credentials to
+access the virtual machine. This is done by running `vagrant ssh-config` from
+`{project_root}` and copying the results into your SSH configuration file
+(usually found at `~/.ssh/config`). This can be done more simply by typing this
+on the host machine:
+
+ vagrant ssh-config --host karmavm >> ~/.ssh/config
+
+The VM will, by default, route its SSH connection through localhost port 2222
+on the host machine and the base user with be vagrant. Point Fabric there when
+running fab commands from `{project_root}`. So the command will look like this:
+
+ fab -H karmavm <commands>
+
+In unix, it might be convenient to create and use an alias like so:
+
+ alias vmfab='fab -H karmavm'
+ vmfab <commands>
+
+Removing a unix alias is done with `unalias`.
+
## Connecting to the VM via SSH
If you have installed a virtual machine using `vagrant up`, you can connect
to it by running `vagrant ssh` from `{project_root}`.
* `{project_root}/reqs/common.txt`
* `{project_root}/reqs/dev.txt`
* `{project_root}/reqs/prod.txt`
+* `{project_root}/reqs/vmdev.txt` (just a combo of dev.txt and prod.txt)
# Thanks
projects / oweals / karmaworld.git / blobdiff