From e8d68f48cab550f5e6345e8db5e873a3187b8f1b Mon Sep 17 00:00:00 2001 From: hisa Date: Tue, 9 Aug 2016 16:37:18 -0400 Subject: [PATCH 1/4] Improve README and add info missing from v0.2.0 --- README.md | 86 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 70 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index de737e3..b8bcb04 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,46 @@ # phoenix-webpack-relay-react (pwr2) -Docker image based on Ubuntu setup with Phoenix+Webpack+Relay+React, with some sugar and conventions to develop and build web applications. +Docker image based on Ubuntu providing a base setup for a Phoenix+Webpack+Relay+React project, with some sugar and conventions to develop and build your own web applications. + +_We will improve docs and code including test coverage in the next releases_ + +## Requirements + +To run this software you need to install [Docker](https://www.docker.com/) on your system. It is very simple and there are a lot of guides and tutorials out there on the Internet. + +>NOTICE: this was only tested in Unix like OS (Mac OS X and Ubuntu) but with should run on Windows without major problems. ## Usage Instructions -Clone this repo to your local and start your own Docker image from these files. You might want to watch this repo so you don't miss upgrades or releases you might to apply to your own projects. +With Docker working on localhost, you can setup this project in 2 ways: + +1. [Setup cloning this GitHub repo and build the image](#setup-cloning-this-github-repo-and-building-the-image). +2. [Setup pulling Docker image from Docker Cloud repository](#setup-pulling-docker-image-from-docker-cloud-repository). + +With all setup, you can start the corresponding containers (_aka services_) by running the following command in your console: + +```bash +docker-compose up +``` -**Notice:** Tags/Releases in this GitHub repo are the equivalent to tags in DockerHub repository, master is the **latest** image in DockerHub. +> you can also just use the [docker-compose.dev.example.yml](docker-compose.dev.example.yml) file directly. -### app user and Elixir commands +```bash +docker-compose -f docker-compose.dev.example.yml up +``` -Most of the code is copied to **APP_HOME=/home/app/webapp**, owned by **app** user. +> add `-d` to the above commands if you want them to execute in background -If you want to go into the container to execute Elixir/Phoenix commands and other stuff you can use `docker exec -it pwr2docker_web_1 bash` and once inside the container execute `su app` to become the **app** user. +When the containers are all up and running, you can go inside the web app container and start the web app so you can play with it. To go inside the container execute the following command in the root directory of the project: +> Assuming the files are placed in a directory named **pwr2-docker** and the generated container is named **pwr2docker_web_1** -You might experience some errors if trying to execute [Elixir](#elixir) commands as root inside the container. +`docker exec -it pwr2docker_web_1 bash` + +Once inside the container, you'll need to switch to **app** user in order to execute Elixir/Phoenix commands. To switch to **app** user run: + +`su app` + +> All the stuff in **/home/app** belongs to **app** user. You might experience some errors if you try to execute [Elixir](#elixir) commands as **root**. Take a look at the Dockerfile to see how all the stuff is installed Once switched to **app** user and in the `APP_HOME` directory, you can start the application server by running: @@ -24,9 +50,39 @@ Once switched to **app** user and in the `APP_HOME` directory, you can start the `iex -S mix phoenix.server` +Now you're ready to start making requests to the web app on the ports you specified. + +### Setup cloning this GitHub repo and building the image + +1. Clone the project to your localhost (_you might want to fork it to your account before_) +2. Copy the [docker-compose.dev.example.yml](docker-compose.dev.example.yml) to **docker-compose.yml** and adjust the ports and [volumes](#about-docker-volumes). +3. Build the image. In the root directory of the project execute `docker build` +4. When the build finishes, **tag** the image to match the _web image_ defined in your **docker-compose** file. For example `docker tag IMAGE_ID pwr2:latest` + +Now you're ready to [start the containers](#usage-instructions) and try some stuff. + +### Setup pulling Docker image from Docker Cloud repository + +1. Open you console or terminal and execute `docker login`. You might not need this. +2. Pull the image from Docker Cloud. Execute `docker pull pwr2:latest`. You can also search for other **tags** besides latest. +3. Copy the [docker-compose.dev.example.yml](docker-compose.dev.example.yml) to **docker-compose.yml** your localhost and adjust the ports, [volumes](#about-docker-volumes) and **image** in **web** section to match the image tag you pulled in above step. + +Now you're ready to [start the containers](#usage-instructions) and try some stuff. + +Once the containers are up and running you can copy the source code of the base project from the container to your localhost with the following command: + +`rsync -rav -e "ssh -p2224 -i insecure_key" --exclude "_build" --exclude "deps" root@localhost:/home/app/webapp/* .` + +> Assuming you exposed the port 2224 to access the container via SSH + +**Notice:** Tags/Releases in this GitHub repo are the equivalent to tags in the Docker Cloud repository, master is the **latest** image in DockerHub. + ### GraphiQL and Relay Examples -Currently, once all setup and with the app running, you can visit http://localhost:4000/graphiql to access a [GraphiQL](https://github.com/graphql/graphiql) IDE, and http://localhost:4000/star-wars to experiment with our implementation of the [Relay Star Wars example](https://github.com/relayjs/relay-examples/tree/master/star-wars) +Currently, once all setup and with the app running, you can: + +1. Visit http://localhost:4000/graphiql to access a [GraphiQL](https://github.com/graphql/graphiql) IDE. +2. Visit http://localhost:4000/star-wars to experiment with our implementation of the [Relay Star Wars example](https://github.com/relayjs/relay-examples/tree/master/star-wars) ## About the technology stack @@ -92,7 +148,7 @@ _We use this instead of_ **brunch.io** _, which is the default to compile static Take a look at [webpack.config.js](webpack.config.js) to see how the loaders and plugins are configured to make things work in the front-end. -See [package.json](package.json) to see the current versions of this NPM packages. +See [package.json](package.json) to see the current versions of these NPM packages. ### Relay & React @@ -114,13 +170,13 @@ Later on, we've added Webpack and its Babel stuff; loader, presets, polyfill and Take a look at **config/dev.exs** to see how we've configured a watcher for `npm start`, this is how you get live reloading when editing files. -### Using +## About Docker Volumes -**TODO:** Improve the following explanation -_Because we're not using volumes due to their extremely low performance we had to copy the project files to include them later in the images with the following command_ : +Although getting better in each release, we still find Docker for Mac volumes to be very slow. That's why we commented out the **volumes** configuration in the **web** section in the **docker-compose.dev.example.yml** file. Obviously, this is not a problem when running Docker on Linux. -`rsync -rav -e "ssh -p2224 -i insecure_key" --exclude "_build" --exclude "deps" root@localhost:/home/app/webapp/* .` +Instead of mounting a volume to work with source code on the container we use [Atom](https://atom.io) _IDE_ with the [remote-sync](https://atom.io/packages/remote-sync) plugin. When this plugin is enabled everytime you save a file it gets automatically copied to the container via SSH. Probably, you might find similar or better strategies with your IDE or you local setup. +If you want to try volumes when running the image pulled directly from Docker Cloud, remember to first get the source code of this project into your localhost in the directory you want to share with the container. This is because the volumes are mounted from host to container (HOST:CONTAINER in the volumes definition in the **docker-compose** file). If the file don't exist in your localhost when mounting a dir they won't exist in your container in the specified directory even if they did exist in the image. ## Issues and Contributing @@ -129,12 +185,10 @@ See [CONTRIBUTING.md](CONTRIBUTING.md). Anyways, just create an issue if you have any question or want something but don't know exactly what it is. ## Core Maintainers -From **[Iporaitech](http://www.iporaitech.com)**, a small startup based in Paraguay. +With love from **[Iporaitech](http://www.iporaitech.com)**, a small startup based in Paraguay. * [Hisa Ishibashi](https://github.com/hisapy) * [Edipo Da Silva](https://github.com/edipox) * [Tania Paiva](https://github.com/taniadaniela) - - ## License This project is licensed under [MIT](https://github.com/iporaitech/pwr2-docker/blob/master/LICENSE). From 196672e8aa5274f40e3e7d66c5ed9a446185a384 Mon Sep 17 00:00:00 2001 From: hisa Date: Tue, 9 Aug 2016 16:37:50 -0400 Subject: [PATCH 2/4] Provide a docker-compose dev example with the volumes section commented out by default --- docker-compose.dev.example.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docker-compose.dev.example.yml b/docker-compose.dev.example.yml index 9ab2176..6068b44 100644 --- a/docker-compose.dev.example.yml +++ b/docker-compose.dev.example.yml @@ -1,8 +1,8 @@ web: image: pwr2:latest command: /sbin/my_init --enable-insecure-key #enable insecure key for dev - volumes: - - .:/home/app/webapp + # volumes: + # - .:/home/app/webapp links: - db ports: From 82f4af601884ecc556bd4acb9be92004b5839571 Mon Sep 17 00:00:00 2001 From: hisa Date: Tue, 9 Aug 2016 16:46:58 -0400 Subject: [PATCH 3/4] Mention Elixir.Agent in the README --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b8bcb04..b1a7146 100644 --- a/README.md +++ b/README.md @@ -82,7 +82,7 @@ Once the containers are up and running you can copy the source code of the base Currently, once all setup and with the app running, you can: 1. Visit http://localhost:4000/graphiql to access a [GraphiQL](https://github.com/graphql/graphiql) IDE. -2. Visit http://localhost:4000/star-wars to experiment with our implementation of the [Relay Star Wars example](https://github.com/relayjs/relay-examples/tree/master/star-wars) +2. Visit http://localhost:4000/star-wars to experiment with our implementation of the [Relay Star Wars example](https://github.com/relayjs/relay-examples/tree/master/star-wars). The _[database](./web/graphql/star_wars_db.ex)_ for this example is implemented as an [Elixir.Agent](http://elixir-lang.org/docs/stable/elixir/Agent.html) ## About the technology stack From 4f816f596b9ec2ca303100b7fc252d8a839f0e57 Mon Sep 17 00:00:00 2001 From: hisa Date: Tue, 9 Aug 2016 16:51:43 -0400 Subject: [PATCH 4/4] Fix example of docker build in the README by adding the missing . --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b1a7146..97a60a0 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ Now you're ready to start making requests to the web app on the ports you specif 1. Clone the project to your localhost (_you might want to fork it to your account before_) 2. Copy the [docker-compose.dev.example.yml](docker-compose.dev.example.yml) to **docker-compose.yml** and adjust the ports and [volumes](#about-docker-volumes). -3. Build the image. In the root directory of the project execute `docker build` +3. Build the image. In the root directory of the project execute `docker build .` 4. When the build finishes, **tag** the image to match the _web image_ defined in your **docker-compose** file. For example `docker tag IMAGE_ID pwr2:latest` Now you're ready to [start the containers](#usage-instructions) and try some stuff.