Skip to content

Latest commit

 

History

History
141 lines (95 loc) · 5.38 KB

SETUP.org

File metadata and controls

141 lines (95 loc) · 5.38 KB

Cornerwise: Server Setup

Running the Server

We’re using Docker (and eventually docker-compose), because it ensures that we’re all working with the same environment. In essence, Docker is a tool for managing lightweight Linux machines.

If you follow the instructions below, you will have the necessary dependencies, including Postgres w/GIS extensions and Django 1.8.

Docker Installation

You’ll only need to run this once. Docker Toolbox is a prerequisite of both the easy instructions and the full instructions below.

Easy Start (OS X or Linux)

This is the recommended way to start the server, unless you need more fine-grained control.

  • cd path/to/cornerwise
  • ./start.sh

    The script will detect if you have Docker Toolbox installed. If you do not, it will find the latest version and download it. Toolbox includes Docker, VirtualBox, and other required utilities. Once you have completed the installation process for Toolbox, rerun the start script. It may take a while, especially if this is the first time you’ve used Docker.

  • Once you’re running inside the container (you should see a prompt beginning with root@[some id]), you can start the server by typing:

    sh /app/start.sh

    Django should start.

  • The easy start script will try by default to remap ports from the virtual machine to localhost, so you should be able to browse to http://localhost:3000 (or another port, if you’ve configured it). If that fails, you can determine the IP address of the VM by opening a new terminal window and typing docker-machine ip dev.

Additional Features

For full usage details of the easy start script, type ./start.sh -h

Full Instructions

Docker Machine

Docker Machine comes Docker Toolbox. It lets you configure different machines, real and virtual, on which to deploy your containers. For the purposes of testing and development, we’ll be using the VirtualBox driver.

Initial Setup

You’ll only need to run this once, after you’ve installed Docker Toolbox.

  • docker-machine create -d virtualbox dev

    Creates a new machine with the name ‘dev’. This may take a minute or two; it has to fetch boot2docker.iso, a stripped-down VM image.

Run

  • eval $(docker-machine env dev)

    This sets up some environment variables to allow the docker command line client to communicate with the dev machine.

  • docker run -it -v $PWD/server:/app -v $PWD/client:/client -v $PWD/data:/data APP_PORT=3000 APP_NAME=cornerwise -p "3000:3000" bdsand/cornerwise /bin/bash

    Creates a new container from the ‘bdsand/cornerwise’ image, which it will fetch from Docker Hub if it’s not present on the local machine. Exposes the ‘server’ directory as /app inside the container. Maps the container’s port 3000 to port 3000 on the virtual machine. Sets APP_PORT and APP_NAME environment variables, which are used by the Django start script. Runs /bin/bash within the new container.

    If you have never run this before, it will need to download the image, which includes (among other things) Python 3, PostGIS, Redis, and GDAL utilities. It weighs in at a few hundred MB.

  • You should see a bash prompt.

    If you see an error that says something like:

    Are you trying to connect to a TLS-enabled daemon without TLS?

    Run: eval $(docker-machine env dev)

    And try the docker command again.

  • sh /app/start.sh

    Bash script to start the server. It starts Postgres and then Django.

Opening in Browser

  • (OS X) Quick way: open http://$(docker-machine ip dev):3000
  • (Linux) If you have xdg-open installed: xdg-open http://$(docker-machine ip dev):3000

    Running docker-machine ip dev) will print out the IP address of the ‘dev’ machine. In our case, this is a VirtualBox VM. Because the VM does not forward its ports to the host (i.e., your computer) by default, you must connect to it using the IP address.

VM Port Forwarding

  • If you’re using VirtualBox, you can set it up to forward, e.g., its port 3000 to your computer’s port 3000 by running:

VBoxManage controlvm dev natpf1 "django,tcp,127.0.0.1,3000,,3000"

“django” can be any name you choose. The first ‘3000’ is the host port. The second ‘3000’ is the VM port. These do not have to be the same.

Additional Notes

  • An image creates a snapshot of a machine. When you start a container from an image, you’re starting clean. Changes you make to unshared folders (including–for now–Postgres data) will not be persisted on the image. When you stop the container, the data will be lost. This is acceptable for us while we stabilize the models, etc.

Troubleshooting

  • If the script hangs while fetching a new image (Using default tag: latest), or if url fetches hang inside the container, it may be an issue with the VM’s networking. I’m not sure exactly what causes it, but you can fix it by running docker-machine restart dev in a fresh terminal window.