Better automate deploy

.gitignore

@@ -106,3 +106,8 @@ src/sous_chef/static
 
 # Ignore generated pdf files.
 src/*.pdf
+
+# the magic docker-compose override file is for overriding settings locally
+# it should not be a part of the repo. If you want per-environment settings,
+# use an explicit `docker-compose -f docker-compose.yml -f docker-compose.environment.yml`
+docker-compose.override.yml

Dockerfile

@@ -2,13 +2,35 @@ FROM python:3.5
 ENV PYTHONUNBUFFERED 1
 RUN mkdir /code
 WORKDIR /code
-ADD requirements.txt /code/
+COPY requirements.txt /code/
+COPY . /code/
+
+# install underlying debian dependencies
 RUN apt-get update
 RUN apt-get install curl gettext -y
 RUN curl -sL https://deb.nodesource.com/setup_8.x | bash -
 RUN apt-get install nodejs build-essential -y
 RUN apt-get install binutils libproj-dev gdal-bin -y
+RUN apt-get clean
+
+# install python dependencies
 RUN pip3 install -r requirements.txt
+
+# install javascript dependencies
 RUN npm install gulp -g
-ADD . /code/
-RUN apt-get clean
+
+# compile front-end "assets" (this should be unnecessary since they're basically just files, but hey, it's 2017)
+# the 'rebuild node-sass' is a patch over a glitch which showed up recently;
+# the tip that fixed it is from https://github.com/sass/node-sass/issues/1387#issuecomment-185451183
+# perhaps it is not truly necessary.
+run mkdir /code/src/sous_chef/static/
+RUN python3 src/manage.py collectstatic --noinput
+WORKDIR /code/tools/gulp
+RUN npm install  # gulp dependencies
+RUN gulp
+WORKDIR /code/
+
+# the default entrypoint for the container
+# when this ends, the container ends, then restarts
+# can be overridden in docker-compose.yml files
+CMD python3 src/manage.py runserver 0.0.0.0:8000

INSTALL.md

@@ -23,20 +23,33 @@ For older Windows versions, you may have to use **Docker Toolbox** (https://www.
 
 ```
 $> git clone https://github.com/savoirfairelinux/sous-chef
-$> docker-compose build
+$> cd sous-chef
 $> docker-compose up
 ```
 
+After this, test it worked by going to http://localhost:8000.
+
 **Notice**: if you see the error "Can't connect to database" in `souschef_web_1`, try Ctrl+C and re-run `docker-compose up`.
 
-(Optional) Running docker-compose with production settings:
+To make changes to the running image, you could re-run it with `docker-compose up --build`, but to speed up development
+you can instead loop-mount the `sous-chef/` directory into the container by running
+
+```
+$> docker-compose -f docker-compose.yml -f docker-compose.dev.yml up
+```
+
+Similarly, you could use the production settings file that uses `gunicorn` to better handle load:
 
 ```
 $> docker-compose -f docker-compose.yml -f docker-compose.prod.yml up
 ```
 
 ## Django initialization
 
+Unfortunately, the bulk of the Django configuration cannot happen until the containers are already built
+and running, because it needs to talk to the database which is in a different container, managed by docker-compose.
+So after you do the first build, you need to manually do some more steps.
+
 In your console:
 
 ```
@@ -58,29 +71,26 @@ $> python3 manage.py createsuperuser
 $> python3 manage.py loaddata sample_data
 ```
 
-## Generate Django assets using gulp
+## (Optional) Generate frontend assets
 
-### Run gulp
+You do not need to run these commands to deploy Sous-Chef, but if during development
+you make changes to anything in the frontend you will need to know at least gulp.
 
-**From container:**
+[gulp](http://gulpjs.com/) is a javascript-based build system.
+We use it to compile and optimize files from `src/frontend/` to `src/sous_chef/static/`.
+We specifically use it to compile scss to css, javascript to minified javascript,
+and images to further-compressed images.
 
-```
-$> docker-compose exec web sh -c "cd tools/gulp && npm install --unsafe-perm && gulp"
-```
-
-Or **from host machine:**
+To run gulp, use:
 
 ```
-$> cd tools/gulp && npm install --unsafe-perm && gulp
-
-# If you don't have the gulp command, try: 
-$> cd tools/gulp && node node_modules/gulp/bin/gulp.js
+$> docker-compose exec web sh -c "cd tools/gulp && gulp"
 ```
 
-Please rest assured that the "unsafe-perm" option will not bring any security risk to sous-chef. The Node.js packages that we are installing here are only used for generating static files, such as images, CSS, JavaScript, etc., and will never be executed from external.
-
-If you have an error with this command, try deleting the folder `tools/gulp/node_modules` completely and rerun it. If the problem still exists, please let us know.
+If you have an error with this command, try deleting the folder `tools/gulp/node_modules` completely and rerun it. If the problem still exists, please let us know, including the versions of node, npm, and gulp that you have.
 
+[collectstatic](https://docs.djangoproject.com/en/1.11/ref/contrib/staticfiles/#collectstatic) is similar, but built into Django.
+We are not using it to manage our own static files, but some of our Django dependencies might need this to be run.
 
 ## Connection to application
 

docker-compose.dev.yml

@@ -0,0 +1,10 @@
+# use as `docker-compose -f docker-compose.yml -f docker-compose.dev.yml up`
+# this causes the the local folder to be loop-mounted into the container
+# so that you can edit code with your normal editors and have the changes
+# immediately be reflected in the running container, without a `docker-compose build`.
+
+version: '3'
+services:
+  web:
+    volumes:
+      - .:/code

docker-compose.prod.yml

@@ -1,4 +1,6 @@
 version: '3'
 services:
   web:
-    command: /bin/bash -c "cd tools/gulp && gulp && cd ../../src && python manage.py collectstatic --noinput && /usr/local/bin/gunicorn sous_chef.wsgi:application -w 2 -b :8000"
+    environment:
+      - SOUSCHEF_ENVIRONMENT_NAME=PROD
+    command: bash -c "cd src/ && /usr/local/bin/gunicorn sous_chef.wsgi:application -w 2 -b :8000"

docker-compose.yml

@@ -14,6 +14,8 @@ services:
       - backend
 
   web:
+    ports:
+      - "127.0.0.1:8000:8000"
     environment:
       - SOUSCHEF_ENVIRONMENT_NAME=DEV
       - SOUSCHEF_VERSION=v1.0-beta