Add setup documentation

.env.template

@@ -1,19 +1,24 @@
 PKPARSE_URL=
 
-# Superuser for postgres. The default is simply 'postgres'. Please change this
-# to something more unique. Avoid unsafe URL characters (`@`, `:`, # `/`, etc)
-POSTGRES_USER=postgres
+# Default user for postgres. The default is simply 'postgres'. Please change
+# this to something more unique. Avoid unsafe URL characters (`@`, `:`, # `/`,
+# etc)
+POSTGRES_USER=pokemon_trade
 
-# Password for postgres. The default is simply 'postgres'. Please change this to
-# something more unique. Avoid unsafe URL characters (`@`, `:`, # `/`, etc)
+# Password for postgres. For docker containers, the default is simply
+# 'postgres'. Please change this to something more unique. For normal use (not
+# docker containers), you should specify the same password used when creating a
+# postgres role. Avoid unsafe URL characters (`@`, `:`, # `/`, etc)
 POSTGRES_PASSWORD=postgres
 
-# Name of the database for the containers to use. The default is
-# `POSTGRES_USER`, or simply `postgres`
+# Name of the database to use. For docker containers, the default is
+# `POSTGRES_USER`, or simply `postgres`.
+# For normal use (not docker containers), please note that the test database
+# will be created as `ENV['POSTGRES_DB'] + "_test"`
 POSTGRES_DB=pokemon_trade_dev
 
-# Port which Rails is exposed on
+# Port which Rails is exposed on, _only used for docker containers_.
 WEB_HOST_PORT=3000
 
-# Port which Postgres is exposed on
+# Port which Postgres is exposed on, _only used for docker containers_.
 DB_HOST_PORT=5432

README.md

@@ -1,15 +1,40 @@
 # Pokemon.trade
 
-### Running the app:
-You will need `config/config.yml`. This file is not committed to the repository.
+Pokemon.trade is a website connecting fellow Pokémon fans together to find and
+trade Pokémon.
 
-To run the app in development, you need to make a Postgres database
-`pokemon_trade_dev`. Then you can run the app via `foreman start -f
-Procfile.dev`.
+## Development Quickstart
 
-For Rails tests, run `rspec`.
-For Javascript tests, run `yarn test`.
+### With Docker and Docker Compose
+Obviously, make sure you have docker and docker-compose installed before
+proceeding.
+
+Although not recommended for long term development, you can use the
+`docker-compose.yml` file to quickly setup a local environment that supports
+on-the-fly editting and hot-reloading of site components.
+
+```bash
+# Copy the .env template to .env
+# After copying, you should edit the configuration as needed.
+cp .env{.template,}
+
+docker-compose up --build -d
+docker-compose exec web rails db:create db:schema:load
+```
+
+### Testing via Docker and Docker Compose
+
+```bash
+docker-compose -f docker-compose.ci.yml up -d
+
+docker-compose -f docker-compose.ci.yml run --rm test_web rails db:wait_for_init db:create spec
+docker-compose -f docker-compose.ci.yml run --rm test_web yarn test
+docker-compose -f docker-compose.ci.yml run --rm test_web rubocop
+docker-compose -f docker-compose.ci.yml run --rm test_web yarn lint
+
+docker-compose -f docker-compose.yml down
+```
+
+**For setting up a local environment or further information, please see the
+[extended setup documentation](docs/LOCAL_SETUP.md).**
 
-docker build --target builder -t pokemon.trade:builder .
-docker build -t pokemon.trade:latest .
-docker run -e RAILS_SERVE_STATIC_FILES=true -e RAILS_ENV=production -e DATABASE_URL=postgres://postgres:postgres@172.17.0.2/pokemon_trade_dev -p 3000:3000 pokemon.trade:latest

docs/LOCAL_SETUP.md

@@ -0,0 +1,82 @@
+# Local Development Setup
+
+## Installing Dependencies
+
+#### tl;dr
+The primary dependencies:
+- Ruby v2.6.3
+- PostgresQL v11.2
+- Node v11.14.0
+
+Potentially useful version info you could have found in the repo:
+- Yarn v1.15.2
+- Bundler v1.17.2
+
+#### Installing Ruby
+
+Use your favorite Ruby version manager. I prefer [RVM](https://rvm.io/):
+```bash
+rvm install ruby-2.6.3
+```
+
+#### Installing PostgreSQL
+Use your system's package manager. For Arch Linux, use pacman:
+```bash
+pacman -S postgresql
+```
+
+If you need to know which
+```bash
+% postgres --version
+=> postgres (PostgreSQL) 11.2
+```
+
+#### Node.js/npm
+Use your system's package manager. For Arch Linux, use pacman:
+```bash
+pacman -S nodejs yarn
+```
+
+## Database setup
+You will need to create a `pokemon_trade` role (or whatever you specify in your
+`.env`, for the `config/database.yml`) and allow it create/manage a database and
+login:
+```bash
+sudo su postgres -c 'psql -c "CREATE ROLE pokemon_trade WITH CREATEDB LOGIN"'
+```
+
+Default role (user) defined in `config/database.yml` is simply `pokemon_trade`.
+Feel free to use something more fitting as needed.
+
+## App setup
+
+#### Running the Rails server
+Copy the .env configuration into place, configure it, then set up the database.
+
+```bash
+# Copy the .env template to .env
+# After copying, you should edit the configuration as needed.
+cp .env{.template,}
+
+bundle exec rails db:create db:schema:load
+rails server
+```
+
+#### Using `webpack-dev-server` for frontend hot module reloading
+Rails will proxy `webpack-dev-server` if it's running. All you need to do is
+start it in addition to the Rails server:
+```bash
+bin/webpack-dev-server
+```
+
+#### Both at once
+Alternatively, if you want a quick command to run both the Rails server and
+webpack-dev-server for hot module reloading for frontend development, start the
+server with `foreman` (instead of `rails server`/`bin/webpack-dev-server`):
+```bash
+gem install foreman
+foreman start -f Procfile.dev
+```
+
+Simply put, `foreman` reads a file and starts a process for each pre-defined
+command.