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`
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 \
+ 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.gz
+ 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
- ./autogen.sh
+ cd fontforge
+ ./bootstrap
./configure --prefix=/usr
make
sudo make install
+ cd ~/
git clone https://github.com/charlesconnell/pdf2htmlEX.git
cd pdf2htmlEX
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, run
- `pip -i {project_root}/reqs/vmdev.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
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}`.
+`{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 127.0.0.1 --port=2222 -u vagrant <commands>
+ fab -H karmavm <commands>
In unix, it might be convenient to create and use an alias like so:
- alias vmfab='fab -H 127.0.0.1 --port=2222 -u vagrant'
+ alias vmfab='fab -H karmavm'
vmfab <commands>
Removing a unix alias is done with `unalias`.
projects / oweals / karmaworld.git / blobdiff