Add README, LICENSE and INSTALLING.md

.rbenv-vars-sample

@@ -1,32 +1,37 @@
-# Parameters for sending mail
-# smtp or mailgun
-MAIL_METHOD=
-MAIL_FROM_ADDRESS=
-
-SMTP_SERVER=
-SMTP_USER=
-SMTP_PASS=
+# ['production', 'development']
+RAILS_ENV=
 
-MAILGUN_DOMAIN=
-MAILGUN_API_KEY=
+# ['en', 'nl']
+AARDBEI_LOCALE=
 
-# To be used in link construction
+# Used in link construction, like 'localhost:3000', 'aardbei.maartenberg.nl'
 AARDBEI_HOSTNAME=
 
-SECRET_KEY_BASE=
-# ['production', 'development']
-RAILS_ENV=
-
-# Set to '1' if in staging and/or not running a 'real' server or assets won't work
+# Set '1' if RAILS_ENV is production, but you're not running a real webserver.
 RAILS_SERVE_STATIC_FILES=
 
-# Database credentials
+# Full path to the cloned directory. (Run `pwd` if unsure)
+AARDBEI_PATH=
+
+# Generate using `rails secret`
+SECRET_KEY_BASE=
+
+# Database credentials if in production
 DB_NAME=
 DB_USER=
 DB_PASS=
 
-# Where are we?
-AARDBEI_PATH=
+# Parameters for sending mail
+MAIL_FROM_ADDRESS=
+# ['smtp', 'sendmail', 'mailgun']
+MAIL_METHOD=
+
+SMTP_SERVER=
+SMTP_USER=
+SMTP_PASS=
+
+MAILGUN_DOMAIN=
+MAILGUN_API_KEY=
 
 # Do we bind to a socket or port?
 PUMA_BIND=

INSTALLING.md

@@ -0,0 +1,258 @@
+# Requirements
+To run Aardbei, you will need a UNIX operating system, which basically means
+that you need to be running either macos or some flavour of Linux.
+Running on Windows might very well be possible, but I haven't tried it.
+
+The Ruby-version Aardbei uses is currently 2.3.3, and to ensure that the version
+is always available, and does not conflict with any system installation of some
+other Ruby version, the supported way to install it is by compiling from source
+using the platform-independent tool [rbenv], with two helper tools called
+[ruby-build] and [rbenv-vars].
+
+You will need the following tools installed in whatever way you like:
+- [Git]
+- Your distro's equivalent of `build-essential` (`make`, `gcc`, probably other
+	tools)
+- Development headers for `openssl`, `zlib` and `readline` (Ubuntu: `sudo apt
+	install libssl-dev zlib1g-dev libreadline-dev`)
+- Nodejs (`apt install nodejs`) for Javascript minifying.
+- In production: a working `postgresql` installation, with the development
+	headers for libpq (`apt install libpq-dev`). Other databases will probably
+	work because ActiveRecord should support it, but I'm using Postgres on my
+	own server, and haven't tested anything besides sqlite yet.
+- In development: libsqlite3 with development headers (`apt install
+	libsqlite3-dev`)
+
+# Installing rbenv, ruby-build, and rbenv-vars, and adding it to your shell
+
+## Installing rbenv
+To not depend on your distro's version of `rbenv` (if any), we install from
+rbenv's repository.
+
+Clone the rbenv repository to your home directory:
+
+```console
+$ git clone https://github.com/rbenv/rbenv.git ~/.rbenv
+```
+
+Try to compile the bash extension:
+
+```console
+$ cd ~/.rbenv; src/configure; make -C src; cd -
+```
+
+Add `rbenv` to your `$PATH` (note the double `>>`, a single `>` will trash your
+`.bashrc`!):
+
+```console
+$ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
+$ echo 'eval "$(rbenv init -)"' >> ~/.bashrc
+$ source ~/.bashrc
+```
+
+## Installing ruby-build, compiling ruby
+`ruby-build` is a plugin for `rbenv` that provides automated compilation and
+installation of Ruby.
+
+Create the plugin-directory, and clone the repository to it:
+
+```console
+$ mkdir -p ~/.rbenv/plugins
+$ git clone https://github.com/rbenv/ruby-build.git ~/.rbenv/plugins/ruby-build
+```
+
+Ensure you have the dependencies listed above installed (`build-essential` and
+the development headers for `openssl`, `libreadline` and `zlib`). Now start the
+compilation of Ruby (this will take a while and will not show a progress bar):
+
+```console
+$ rbenv install 2.3.3
+```
+
+If all is well, you will get some success message, if you have an error the
+script usually tells you what went wrong.
+
+## Installing rbenv-vars
+`rbenv-vars` is another plugin for `rbenv` that allows us to easily set
+environment variables by listing them in the file `.rbenv-vars`.
+
+Install it by cloning the repository:
+
+```console
+$ git clone https://github.com/rbenv/rbenv-vars.git ~/.rbenv/plugins/rbenv-vars
+```
+
+Copy the template `.rbenv-vars-sample` to `.rbenv-vars`, and set the
+environment to `production` or `development`, and the locale to `en` or `nl`,
+without quotes.
+
+```
+RAILS_ENV=development
+# ...
+AARDBEI_LOCALE=en
+```
+
+Set `AARDBEI_HOSTNAME` to the hostname your copy is going to run under (in development it's going to be `localhost:3000`:
+
+```
+AARDBEI_HOSTNAME=aardbei.maartenberg.nl
+```
+
+If you're planning to run in the production environment, but without a real webserver to serve your assets, set `RAILS_SERVE_STATIC_FILES=1`.
+
+Set `AARDBEI_PATH` to the full path of the cloned directory, like `AARDBEI_PATH=/home/aardbei/aardbei`.
+
+# Installing dependencies
+Aardbei's dependencies in Ruby are managed using Bundler. To install it, rbenv
+needs to know which version of Ruby we're using. This is stored in the file
+`.ruby-version`.
+
+Install bundler by moving to your cloned copy of Aardbei, and running:
+
+```console
+$ gem install bundler
+```
+
+Depending on your environment, run either:
+
+```console
+$ bundle install --without=production # in development
+$ bundle install --without='development test' # in production
+```
+
+If all went well, run `rbenv rehash` to add the new executables to your shell,
+and test that the installation worked by running `rails`. You should see some
+output listing the available subcommands.
+
+Open up your `.rbenv-vars` again, run the command `rails secret`, and set it as your `SECRET_KEY_BASE`:
+
+```console
+SECRET_KEY_BASE=a3a43b...
+```
+
+# Setting up the database
+
+## In development: SQLite
+When running in the development environment, the database is saved as a file in
+the `db` folder. To create it, and pre-fill some test data, run this command:
+
+```console
+$ RAILS_ENV=development rails db:setup
+```
+
+Note: __The test data currently includes a hardcoded admin user, change this if
+needed!__
+
+## In production: Postgresql
+If you're not already running Postgresql, install it using `sudo apt install
+postgresql-9.5`.
+
+Create a database and user with the following commands:
+
+```console
+$ sudo -u postgres psql
+postgres=# CREATE ROLE aardbei WITH LOGIN PASSWORD 'aardbei123';
+CREATE ROLE
+postgres=# CREATE DATABASE aardbei WITH OWNER = aardbei;
+CREATE DATABASE
+postgres=# GRANT ALL PRIVILEGES ON DATABASE aardbei TO aardbei;
+GRANT
+postgres=# \q
+```
+
+You will probably want to generate a real password for the database instead of
+`'aardbei123'`, this can be done by running `rails secret`.
+
+Fill in your database details in `.rbenv-vars`:
+
+```
+DB_NAME=aardbei
+DB_USER=aardbei
+DB_PASS=aardbei123
+```
+
+Now set up the database:
+
+```console
+$ rails db:setup
+```
+
+# Setting up email
+Aardbei needs to be able to email in order to send password reset links and
+reminders. Set the address for the `From:` field by setting:
+
+```
+MAIL_FROM_ADDRESS=aardbei@maartenberg.nl
+```
+
+Choose one of the below methods to deliver your mails:
+
+## Using Sendmail
+If your system already has working `sendmail`, set `MAIL_METHOD` to `sendmail`.
+
+```
+MAIL_METHOD=sendmail
+```
+
+## Using Mailgun
+If you have your own domain, you can use the free [Mailgun] tier to deliver your emails. In `.rbenv-vars`, set:
+
+```
+MAIL_METHOD=mailgun
+
+# ...
+
+MAILGUN_DOMAIN=your.domain.mg
+MAILGUN_API_KEY=key-abcdefpdftexexezip
+```
+
+## Using SMTP
+You can use a SMTP server. Set:
+
+```
+MAIL_METHOD=smtp
+
+SMTP_SERVER=email.example.com
+SMTP_USER=coolskeleton95
+SMTP_PASS=aardbei123
+```
+
+# Create an Admin person
+If you're not me, you'll want to create your own user. Run:
+
+```console
+$ rails console
+> p = Person.new
+> p.first_name = 'Maarten'
+> p.infix = 'van den'
+> p.last_name = 'Berg'
+> p.email = 'youremail@example.com'
+> p.is_admin = 1
+> p.save
+> exit
+```
+
+Note that this has not yet set a password for you: to do that, we need to run a server.
+
+# Running the server directly / in development mode
+To start the server, run the command `rails server`. Your terminal will block
+until you press Control-C. In addition to this, you will need to be running the
+jobs worker to be able to send emails. To start it, run (in another terminal or
+before starting the server) `bin/delayed_job start` (or run in the foreground
+with `bin/delayed_job run`).
+
+# Running in production
+TODO.
+
+# Activating your admin user
+To activate your admin user, have your server running and go to
+`http://localhost:3000/register`. Enter the email address you entered when you
+created your Person, and follow the instructions.
+
+<!--* Deployment instructions-->
+
+[rbenv]: https://github.com/rbenv/rbenv
+[ruby-build]: https://github.com/rbenv/ruby-build
+[rbenv-vars]: https://github.com/rbenv/rbenv-vars
+[Git]: https://git-scm.com
+[Mailgun]: https://mailgun.com

LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Maarten van den Berg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,24 +1,24 @@
-# README
+# Aardbei, "sprankelprachtig aan- en afmeldsysteem"
 
-This README would normally document whatever steps are necessary to get the
-application up and running.
+Aardbei is a tool meant to simplify signing up for many activities organized
+within the same group of people.
+The organizers of the activities can set when the activity starts and ends,
+a description and location, and can set a deadline for signing up after which
+only the organizers can change the information, and remind people who haven't
+responded yet automatically at a set time.
 
-Things you may want to cover:
+Planned features:
 
-* Ruby version
+* Random distribution of participants of an activity into subgroups
+* Automatic information email to organizers of activities
 
-* System dependencies
+# Screenshots
+See [here][screenshots]. The screenshots show the two main views: the
+dashboard, showing an overview of the user's activities, and the detail view for
+an activity.
 
-* Configuration
+# Installing
+See [the install guide][installing].
 
-* Database creation
-
-* Database initialization
-
-* How to run the test suite
-
-* Services (job queues, cache servers, search engines, etc.)
-
-* Deployment instructions
-
-* ...
+[screenshots]: doc/screenshots/
+[installing]: INSTALLING.md