diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index fd8dc47769..db5ed0a65b 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -4,7 +4,7 @@ This is a general guide to setting up an Open Food Network **development environ ### Requirements -The fastest way to make it work locally is to use Docker, you only need to setup git, see the [Docker setup guide](DOCKER.md). +The fastest way to make it work locally is to use Docker, you only need to setup git, see the [Docker setup guide](docker/README.md). Otherwise, for a local setup you will need: * Ruby 2.3.7 and bundler * PostgreSQL database diff --git a/docker/README.md b/docker/README.md new file mode 100644 index 0000000000..d08cdd32d7 --- /dev/null +++ b/docker/README.md @@ -0,0 +1,57 @@ +# Docker Scripts + +## What's the point? +* Setting up the Open Food Network app on your local machine is quick and easy with the aid of Docker and Docker Compose. +* Docker provides a common virtual environment available to all developers and resolves the infamous "but it works on my machine" problem. +* Use the scripts in this directory to execute tasks in Docker. Please note that these scripts are intended to be executed from this app's root directory. These scripts allow you to bypass the need to keep typing "docker-compose run --rm web". + +## Installing Docker +* You should have at least 2 GB free on your local machine to download Docker images and create Docker containers for this app. +* Docker installation instructions are at https://docs.docker.com/install/. +* Docker Compose installation instructions are at https://docs.docker.com/compose/install/. +* To run Docker commands as a regular user instead of as root (with sudo), follow the instructions at https://docs.docker.com/engine/install/linux-postinstall/. + +## Getting Started +* Open a terminal with a shell. +* Clone the repository. If you're planning on contributing code to the project (which we [LOVE](CONTRIBUTING.md)), begin by forking this repo with the Fork button in the top-right corner of this screen. +* Use git clone to copy your fork onto your local machine. +```sh +$ git clone https://github.com/YOUR_GITHUB_USERNAME_HERE/openfoodnetwork +``` +* Otherwise, if you just want to get things running, clone from the OFN main repo: + +```sh +$ git clone git@github.com:openfoodfoundation/openfoodnetwork.git +``` +* Go at the root of the app: + +```sh +$ cd openfoodnetwork +``` +* Download the Docker images, build the Docker containers, seed the database with sample data, AND log the screen output from these tasks: +```sh +$ docker/build +``` +* Run the Rails server and its required Docker containers: + +```sh +$ docker/server +``` +* The default admin user is 'ofn@example.com' with the password 'ofn123'. +* View the app in the browser at `http://localhost:3000`. +* You will then get the trace of the containers in the terminal. You can stop the containers using Ctrl-C in the terminal. +* You can find some useful tips and commands [here](https://github.com/openfoodfoundation/openfoodnetwork/wiki/Docker:-useful-tips-and-commands). + +### Troubleshooting +If you are using Windows and having issues related to the ruby-build not finding a definition for the ruby version, you may need to follow these commands [here](https://stackoverflow.com/questions/2517190/how-do-i-force-git-to-use-lf-instead-of-crlf-under-windows/33424884#33424884) to fix your local git config related to line breaks + +## Script Summary +* docker/build: This script builds the Docker containers specified for this app, seeds the database, and logs the screen output for these operations. After you use "git clone" to download this repository, run the docker/build script to start the setup process. +* docker/server: Use this script to run this app in the Rails server. This script executes the "docker-compose up" command and logs the results. If all goes well, you will be able to view this app on your local browser at http://localhost:3000/. +* docker/test: Use this script to run the entire test suite. +* docker/run: Use this script to run commands within the Docker container. If you want shell access, enter "docker/run bash". To execute "ls -l" within the Docker container, enter "docker/run ls -l". +* docker/seed: Use this script to seed the database. Please note that this process is not compatible with simultaneously running the Rails server or tests. +* docker/nuke: Use this script to delete all Docker images and containers. This fully resets your Docker setup and is useful for making sure that the setup procedure specified for this app is complete. +* docker/cop: This script runs RuboCop. + + diff --git a/docker/build b/docker/build new file mode 100755 index 0000000000..f3966951f8 --- /dev/null +++ b/docker/build @@ -0,0 +1,8 @@ +#!/bin/bash +set -e + +# This script builds the Docker container, seeds the app with sample data, and logs the screen output. + +DATE=`date +%Y%m%d-%H%M%S-%3N` +docker/build-log 2>&1 | tee log/build-$DATE.log +docker/seed 2>&1 | tee log/seed-$DATE.log diff --git a/docker/build-log b/docker/build-log new file mode 100755 index 0000000000..7e7903c2a1 --- /dev/null +++ b/docker/build-log @@ -0,0 +1,12 @@ +#!/bin/bash +set +e + +docker-compose down -v --remove-orphans +wait +echo '###########################' +echo 'BEGIN: docker-compose build' +echo '###########################' +docker-compose build # Set up the Docker containers +echo '##############################' +echo 'FINISHED: docker-compose build' +echo '##############################' diff --git a/docker/cop b/docker/cop new file mode 100755 index 0000000000..948ea467d5 --- /dev/null +++ b/docker/cop @@ -0,0 +1,11 @@ +#!/bin/bash + +# This script runs RuboCop. + +echo '------------------------------------------------------' +echo 'BEGIN: docker-compose run --rm web bundle exec rubocop' +echo '------------------------------------------------------' +docker-compose run --rm web bundle exec rubocop +echo '----------------------------------------------------' +echo 'END: docker-compose run --rm web bundle exec rubocop' +echo '----------------------------------------------------' diff --git a/docker/nuke b/docker/nuke new file mode 100755 index 0000000000..737c63b107 --- /dev/null +++ b/docker/nuke @@ -0,0 +1,28 @@ +#!/bin/bash + +# This script destroys all Docker containers, images, and networks. +# SOURCE: https://gist.github.com/JeffBelback/5687bb02f3618965ca8f + +docker/nukec + +echo '-----------------------' +echo 'docker network prune -f' +docker network prune -f + +echo '--------------------------------------' +echo 'Killing and removing all Docker images' +for i in $(docker images -a -q) +do + docker kill $i; wait; + docker rmi -f $i; wait; +done; + +echo '------------' +echo 'docker ps -a' +docker ps -a + +echo '----------------' +echo 'docker images -a' +docker images -a + +wait diff --git a/docker/nukec b/docker/nukec new file mode 100755 index 0000000000..cebba9db4f --- /dev/null +++ b/docker/nukec @@ -0,0 +1,15 @@ +#!/bin/bash + +# This script destroys all Docker containers but leaves the Docker images alone. + +echo '------------------------------------------' +echo 'Killing and removing all Docker containers' +for i in $(docker ps -a -q) +do + docker kill $i; wait; + docker rm -f $i; wait; +done; + +echo '------------' +echo 'docker ps -a' +docker ps -a diff --git a/docker/run b/docker/run new file mode 100755 index 0000000000..3975c87d32 --- /dev/null +++ b/docker/run @@ -0,0 +1,22 @@ +#!/bin/bash + +set -e + +# Use this script to execute commaands in the Docker container. +# Example: To run the "ls -l" command in the Docker container, enter the command "docker/run ls -l". + +function cleanup { + # capture exit code + code=$? + echo "cleaning up" + + # ignore errors + set +e + docker-compose down + + exit $code +} + +trap cleanup EXIT + +docker-compose run --rm web $@ diff --git a/docker/seed b/docker/seed new file mode 100755 index 0000000000..f3b519146a --- /dev/null +++ b/docker/seed @@ -0,0 +1,27 @@ +#!/bin/bash + +# This is the data seeding script. + +echo '------------------------------------------------------------' +echo 'BEGIN: docker-compose run --rm web bundle exec rake db:reset' +echo '------------------------------------------------------------' +docker-compose run --rm web bundle exec rake db:reset +echo '----------------------------------------------------------' +echo 'END: docker-compose run --rm web bundle exec rake db:reset' +echo '----------------------------------------------------------' + +echo '-------------------------------------------------------------------' +echo 'BEGIN: docker-compose run --rm web bundle exec rake db:test:prepare' +echo '-------------------------------------------------------------------' +docker-compose run --rm web bundle exec rake db:test:prepare +echo '-----------------------------------------------------------------' +echo 'END: docker-compose run --rm web bundle exec rake db:test:prepare' +echo '-----------------------------------------------------------------' + +echo '-------------------------------------------------------------------' +echo 'BEGIN: docker-compose run --rm web bundle exec rake ofn:sample_data' +echo '-------------------------------------------------------------------' +docker-compose run --rm web bundle exec rake ofn:sample_data +echo '-----------------------------------------------------------------' +echo 'END: docker-compose run --rm web bundle exec rake ofn:sample_data' +echo '-----------------------------------------------------------------' diff --git a/docker/server b/docker/server new file mode 100755 index 0000000000..fef22b16d9 --- /dev/null +++ b/docker/server @@ -0,0 +1,7 @@ +#!/bin/bash +set -e + +# This script runs the Rails server and logs the screen output. + +DATE=`date +%Y%m%d-%H%M%S-%3N` +docker/server-log 2>&1 | tee log/server-$DATE.log diff --git a/docker/server-log b/docker/server-log new file mode 100755 index 0000000000..08f0d3487e --- /dev/null +++ b/docker/server-log @@ -0,0 +1,9 @@ +#!/bin/bash +set +e + +echo '########################' +echo 'BEGIN: docker-compose up' +echo '########################' +echo 'View this app in your web browser at' +echo 'http://localhost:3000/' +docker-compose up diff --git a/docker/test b/docker/test new file mode 100755 index 0000000000..3420c7595b --- /dev/null +++ b/docker/test @@ -0,0 +1,7 @@ +#!/bin/bash +set -e + +# This script runs the entire test suite AND logs the screen output. + +DATE=`date +%Y%m%d-%H%M%S-%3N` +docker/test-log 2>&1 | tee log/test-$DATE.log diff --git a/docker/test-log b/docker/test-log new file mode 100755 index 0000000000..662747664e --- /dev/null +++ b/docker/test-log @@ -0,0 +1,17 @@ +#!/bin/bash + +echo '-------------------------------------------------------------------' +echo 'BEGIN: docker-compose run --rm web bundle exec rake db:test:prepare' +echo '-------------------------------------------------------------------' +docker-compose run --rm web bundle exec rake db:test:prepare +echo '-----------------------------------------------------------------' +echo 'END: docker-compose run --rm web bundle exec rake db:test:prepare' +echo '-----------------------------------------------------------------' + +echo '---------------------------------------------------------' +echo 'BEGIN: docker-compose run --rm web bundle exec rspec spec' +echo '---------------------------------------------------------' +docker-compose run --rm web bundle exec rspec spec +echo '-------------------------------------------------------' +echo 'END: docker-compose run --rm web bundle exec rspec spec' +echo '-------------------------------------------------------'