expand installation instructions

for #12

README.md

@@ -8,6 +8,26 @@ Compass is a GPS tracking server that stores data in [flat files](https://github
 
 In the `compass` directory, copy `.env.example` to `.env` and fill in the details. Install the dependencies with composer.
 
+```
+$ composer install
+```
+
+If you're using the database queue driver (`QUEUE_DRIVER=database` defined in `.env`), you'll need to create the migration for that table and run it:
+
+* `php artisan queue:table`
+* `php artisan migrate`
+
+Otherwise if you're using Redis, make sure you've installed the Redis server and set `QUEUE_DRIVER=redis`.
+
+Make sure the storage folder you've defined in `STORAGE_DIR` is writable by the web server (or by the PHP process if you're using php-fpm).
+
+To process jobs on the queue, run
+
+```
+$ php artisan queue:listen
+```
+
+For more details on how to configure this to run in the background, see https://lumen.laravel.com/docs/5.1/queues#running-the-queue-listener
 
 ## API
 

compass/.env.example

@@ -1,26 +1,43 @@
-BASE_URL=http://compass.p3k.io/
-DEFAULT_AUTH_ENDPOINT=https://indieauth.com/auth
-ATLAS_BASE=http://atlas.p3k.io/
+# Where you've installed Compass
+BASE_URL=https://compass.example.com/
+
+# Atlas is used for geocoding trips
+# Source code: https://github.com/aaronpk/Atlas
+ATLAS_BASE=https://atlas.p3k.io/
 
+# Make sure the web server or PHP process can write here
 STORAGE_DIR=/var/compass/data
 
-APP_ENV=local
-APP_DEBUG=true
-APP_KEY=SomeRandomKey!!!
-
-APP_LOCALE=en
-APP_FALLBACK_LOCALE=en
+# Set APP_KEY to a 32 character string
+APP_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
+# Define your database connection
 DB_CONNECTION=mysql
 DB_HOST=localhost
 DB_PORT=3306
-DB_DATABASE=homestead
-DB_USERNAME=homestead
+DB_DATABASE=compass
+DB_USERNAME=compass
 DB_PASSWORD=secret
 
-CACHE_DRIVER=memcached
-SESSION_DRIVER=memcached
+# Cookie driver is probably fine. Alternate options: 
+# https://lumen.laravel.com/docs/5.1/session
+SESSION_DRIVER=cookie
+SESSION_LIFETIME=500000
+
+# Processing trips is done on a job queue. If using the database queue,
+# you'll need to create the jobs table. See details in the readme.
 QUEUE_DRIVER=database
+# QUEUE_DRIVER=redis
+
+DEFAULT_AUTH_ENDPOINT=https://indieauth.com/auth
+
+APP_ENV=local
+APP_DEBUG=true
+
+APP_LOCALE=en
+APP_FALLBACK_LOCALE=en
+
+#CACHE_DRIVER=memcached
 
 # MAIL_DRIVER=smtp
 # MAIL_HOST=mailtrap.io