Merge pull request #1127 from metamaps/update-docs

update docs

README.md

@@ -28,44 +28,19 @@ Metamaps is developed and maintained by a distributed, nomadic community compris
 - If you would like to report a bug, please check the [issues][contributing-issues] section in our [contributing instructions][contributing].
 - If you would like to get set up as a developer, that's great! Read on for help getting your development environment set up.
 
-## Installation
+## Installation for local use or development of Metamaps
 
-If you are on Mac or Ubuntu you can use the following instructions to quickly get a local copy of metamaps up and running using a Vagrant virtualbox. Don't be intimidated, it's easy!
+First off is getting the code downloaded to your computer. You can download a zip file from github, but if you've got `git` you can just run `git clone https://github.com/metamaps/metamaps` in your terminal.
-```
-There are two options for cloning the repository - the simplest way is the first one since you don't need to set up SSH keys:
-git clone https://github.com/metamaps/metamaps
 
-OR
+There are instructions for setup on various platforms, with particular support for Mac and Ubuntu, which can be found here:
+- [Mac Install Walkthrough][mac-installation]
+- [Ubuntu Install Walkthrough][ubuntu-installation]
 
-git clone git@github.com:metamaps/metamaps.git
+If you prefer to isolate your install in a virtual machine, you may find it simpler to setup using Vagrant:
-```
+- [Vagrant installation][vagrant-installation]
-Now ensure you have VirtualBox and Vagrant installed on your computer
-```
-cd metamaps
-./bin/configure.sh
-```
-This will do all the setup steps to make Metamaps work with a bit of behind the scenes ninja magick.
 
-To start servers which will run metamaps you can then run:
+We don't promise support for Windows, but at one point we had it running and we've kept those docs available for reference
-```
+- [Outdated Windows Walkthrough][windows-installation]
-./bin/start
-```
-To stop them:
-```
-./bin/stop
-```
-With your webservers running, open a web browser and go to `http://localhost:3000`
-
-You can sign in with the default account
-email: `user@user.com`
-password: `toolsplusconsciousness`
-OR create a new account at `/join`, and use access code `qwertyui`
-
-Start mapping and programming!
-
-We haven't set up instructions for using Vagrant on Windows, but there are instructions for a manual setup here:
-
-- [For Windows][windows-installation]
 
 ## Licensing information
 
@@ -81,4 +56,7 @@ Copyright (c) 2017 Connor Turland
 [license]: https://github.com/metamaps/metamaps/blob/develop/LICENSE
 [contributing]: https://github.com/metamaps/metamaps/blob/develop/doc/CONTRIBUTING.md
 [contributing-issues]: https://github.com/metamaps/metamaps/blob/develop/doc/CONTRIBUTING.md#reporting-bugs-and-other-issues
+[mac-installation]: https://github.com/metamaps/metamaps/blob/develop/doc/MacInstallation.md
+[ubuntu-installation]: https://github.com/metamaps/metamaps/blob/develop/doc/UbuntuInstallation.md
+[vagrant-installation]: https://github.com/metamaps/metamaps/blob/develop/doc/VagrantInstallation.md
 [windows-installation]: https://github.com/metamaps/metamaps/blob/develop/doc/WindowsInstallation.md

Vagrantfile

@@ -37,7 +37,7 @@ Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
   config.vm.box = 'trusty64'
   config.vm.box_url = 'http://cloud-images.ubuntu.com/vagrant/trusty/current/trusty-server-cloudimg-amd64-vagrant-disk1.box'
   config.vm.network :forwarded_port, guest: 3000, host: 3000
-  config.vm.network :forwarded_port, guest: 5001, host: 5001
+  config.vm.network :forwarded_port, guest: 5000, host: 5000
   config.vm.network 'private_network', ip: '10.0.1.11'
   config.vm.synced_folder '.', '/vagrant', nfs: true
 

doc/MacInstallation.md

@@ -1,21 +1,19 @@
 # OSX Install
 
-If you are doing an upgrade and or recent pull for changes you will need to change your default ruby package from 2.1.1 to ruby 2.1.2
+Install rvm (ruby version manager)
-
-Some of these steps are pulled from http://www.moncefbelyamani.com/how-to-install-postgresql-on-a-mac-with-homebrew-and-lunchy/
-
-Install homebrew
 
     \curl -sSL https://get.rvm.io | bash -s stable --rails
+ 
+Use rvm to install Ruby version 2.3.0
+
     rvm install 2.3.0 --with-gcc=clang
     rvm use 2.3.0
-    gem install lunchy 
 
-Now install homebrew. 
+Now install homebrew. (a package manager for mac)
 
     ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
 
-Then install nodejs and ES6 code
+Then install nodejs (make sure its version 6.11.1 or greater)
 
     brew install nodejs
     npm install
@@ -29,7 +27,7 @@ And postgresql:
 
 Set a password, then start the service:
 
-    lunchy start postgres
+    brew services start postgresql
 
 Change directory to the metamaps git repository, and run:
 
@@ -37,9 +35,32 @@ Change directory to the metamaps git repository, and run:
 
 Copy the .example-env file and rename it to .env. Then modify the DB_USERNAME and DB_PASSWORD values to match the postgres username and password you set
 
+Now use rake to create and set up the database
+
     rake db:create
     rake db:schema:load
     rake db:seed
+
+To start the rails server:
+
     rails server
+    
+To start the realtime server:
+
+    node realtime/realtime-server.js
+    
+NOTE: if you want to actively develop on the javascript in `/frontend` use
+
+    npm run build:watch
+to start a webpack build process that updates the build everytime you make code changes
 
 Now open a browser to http://localhost:3000!
+    
+Sign in with the default account
+
+    email: user@user.com
+    password: toolsplusconsciousness
+
+OR create a new account at /join, and use access code 'qwertyui'
+
+Start mapping and programming!

doc/UbuntuInstallation.md

@@ -80,18 +80,23 @@ Use these commands to set the password to 3112 and then quit:
 now we can use rake to create, load the schema into, and load db/seeds.rb
 into the postgres database:
 
-    rake db:setup
+    rake db:create
+    rake db:schema:load
+    rake db:seed
 
 Open a new terminal, navigate to the metamaps directory, and execute the
 server: 
     
     rails s
+    
+NOTE: if you want to actively develop on the javascript in /frontend use
+
+    npm run build:watch
 
 and dont forget to run the other server for realtime...
 
-    cd realtime
+    node realtime/realtime-server.js
-    npm install
+to start a webpack build process that updates the build everytime you make code changes
-    node realtime-server.js
 
 Now you're all set enjoy your personal server of metamaps :) Navigate your browser to localhost:3000 once you have the server running. Sign in with the default account
 

doc/VagrantInstallation.md

@@ -0,0 +1,29 @@
+Now ensure you have VirtualBox and Vagrant installed on your computer
+```
+cd metamaps
+./bin/configure.sh
+```
+
+This will do all the setup steps to make Metamaps work with a bit of behind the scenes ninja magick.
+
+To start servers which will run Metamaps you can then run:
+```
+./bin/start
+```
+
+To stop them:
+```
+./bin/stop
+```
+
+With your webservers running, open a web browser and go to `http://localhost:3000`
+
+You can sign in with the default account
+
+email: `user@user.com`
+
+password: `toolsplusconsciousness`
+
+OR create a new account at `/join`, and use access code `qwertyui`
+
+Start mapping and programming!

doc/WindowsInstallation.md

@@ -1,3 +1,5 @@
+DISCLAIMER: This tutorial is liable to be out of date, and we don't necessarily support Windows development. If you are set on installing Metamaps on Windows, it may be worthwhile to look at the Mac and Ubuntu docs for up to date information on what Metamaps requires to run. 
+
 Before you begin, you'll need to install stuff:
 
 Ruby, Git, and Rails: http://railsinstaller.org/en
@@ -39,7 +41,7 @@ fail unless `.env` is correctly configured and Postgres is running.
 
     rake db:create
     rake db:schema:load
-    rake db:fixtures:load
+    rake db:seed
 
 And you're set up! At this point, you should be able to run the server at any
 time with only one command; you don't need to repeat any of the previous steps