3 files changed, 203 insertions, 0 deletions
diff --git a/doc/contributing.md b/doc/contributing.md
new file mode 100644
index 0000000..a31ed4f
--- /dev/null
+++ b/doc/contributing.md
@@ -0,0 +1,33 @@
+# Contributing to travelynx Development
+
+First, a note upfront: travelynx is a hobby project.
+While I appreciate suggestions, bug reports, and merge requests / patches, I want to make sure that it remains a hobby project and does not turn into a chore.
+As such, please do not expect a timely response to anything you submit.
+I typically only address issues and merge requests when I have the capacity for them _and_ when doing so does not feel like a chore.
+
+That being said, I do appreciate bug reports, feature requests, and (simple!) patches, even if I may take quite a while to address or review them.
+If you are planning a more involved patch set, please get in touch first.
+
+## Translations
+
+This is probably the easiest way to improve the life of any travelynx users who are not native German speakers.
+Note that travelynx does _not_ use Weblate.
+
+### Updating or Extending Translations
+
+* Look at the [translation reference](../share/locales/reference.md)
+* Pick a language that you'd like to fix / update / extend
+* Adjust the corresponding `share/locales/ab-CD.po` file
+* Open a merge request, either on [Codeberg](https://codeberg.org/derf/travelynx/pulls) or [GitHub](https://github.com/derf/travelynx/pulls)
+
+### Adding a new Language
+
+* Copy `share/locales/template.pot` to `share/locales/ab-CD.po`, replacing ab-CD with the appropriate language code
+* Add the language / locale to  `$self->helper(loc_handle …` in `lib/Travelynx.pm`
+* Add the language / locale to  `templates/language.html.ep`
+* Provide as many translations as you feel comfortable with – partial translation files are fine; any entry left as `msgstr ""` will cause travelynx to fall back to English or German.
+* Open a merge request, either on [Codeberg](https://codeberg.org/derf/travelynx/pulls) or [GitHub](https://github.com/derf/travelynx/pulls)
+
+## Bug Reports
+
+You may report bugs and request features either on [Codeberg](https://codeberg.org/derf/travelynx/issues) or [GitHub](https://github.com/derf/travelynx/issues).
diff --git a/doc/setup.md b/doc/setup.md
new file mode 100644
index 0000000..82a2348
--- /dev/null
+++ b/doc/setup.md
@@ -0,0 +1,136 @@
+# Hosting your own travelynx
+
+This document describes how to host your own travelynx instance.
+
+## Dependencies
+
+ * perl ≥ 5.20
+ * carton
+ * build-essential
+ * libpq-dev
+ * git
+
+## Installation
+
+travelynx depends on a set of Perl modules which are documented in `cpanfile`.
+After installing the dependencies mentioned above, you can use carton to
+install Perl depenencies locally. You may alsobe able to use cpanminus;
+however this method is untested.
+
+In the project root directory (where `cpanfile` resides), run
+
+```
+carton install --deployment
+```
+
+and set `PERL5LIB=.../local/lib/perl5` before executing any travelynx
+commands (see configs in the examples directory) or wrap them with `carton
+exec`, e.g. `carton exec hypnotoad index.pl`
+
+## Setup
+
+First, you need to set up a PostgreSQL database so that travelynx can store
+user accounts and journeys. It must be at least version 9.4 and must use a
+UTF-8 locale. The following steps describe setup on a Debian 9 system;
+setup on other distributions should be similar.
+
+* Write down a strong random password
+* Create a postgres user for travelynx: `sudo -u postgres createuser -P travelynx`
+  (enter password when prompted)
+* Create the database: `sudo -u postgres createdb -O travelynx travelynx`
+* Copy `examples/travelynx.conf` to the application root directory
+  (the one in which `index.pl` resides) and edit it. Make sure to configure
+  db, cache, mail, and secrets.
+* Initialize the database: `carton exec perl index.pl database migrate`
+  or `PERL5LIB=local/lib/perl5 perl index.pl database migrate`
+
+Your server also needs to be able to send mail. Set up your MTA of choice and
+make sure that the sendmail binary can be used for outgoing mails. Mail
+reception on the server is not required.
+
+Finally, configure the web service:
+
+* Set up a travelynx service using the service supervisor of your choice
+  (see `examples/travelynx.service` for a systemd unit file)
+* Configure your web server to reverse-provy requests to the travelynx
+  instance. See `examples/nginx-site` for an nginx config.
+* Install a `timeout 5m perl index.pl work -m production` cronjob. It is used
+  to update realtime data and perform automatic checkout and should run
+  every three minutes or so, see `examples/cron`.
+
+You can now start the travelynx service, navigate to the website and register
+your first account. There is no admin account, all management is performed
+via cron or (in non-standard cases) on the command line.
+
+Please open an issue on <https://github.com/derf/travelynx/issues> or send a
+mail to derf+travelynx@finalrewind.org if there is anything missing or
+ambiguous in this setup manual.
+
+Note that Deutsche Bahn have put parts of their API behind an IP reputation
+filter. In general, checkins with the bahn.de backend will only be possible if
+travelynx is accessing it from a residential (non-server) IP range.  See the
+dbris bahn.de proxy / proxies setting in `example/travelynx.conf` for
+workarounds.
+
+## Updating
+
+It is recommended to run travelynx directly from the git repository. When
+updating, the workflow depends on whether schema updates need to be applied
+or not.
+
+```
+git pull
+carton install --deployment # if you are using carton: update dependencies
+chmod -R a+rX . # only needed if travelynx is running under a different user
+if perl index.pl database has-current-schema; then
+    systemctl reload travelynx
+else
+    systemctl stop travelynx
+    perl index.pl database migrate
+    systemctl start travelynx
+fi
+```
+
+Note that this is subject to change -- the application may perform schema
+updates automatically in the future. If you used carton for installation,
+use `carton exec perl ...` in the snippet above; otherwise, export
+`PERL5LIB=.../local/lib/perl5`.
+
+## Setup with Docker
+---
+
+Note that travelynx Docker support is experimental and, in its current form,
+far from best practices. Pull requests are appreciated.
+
+First, you need to set up a PostgreSQL database so that travelynx can store
+user accounts and journeys. It must be at least version 9.4 and must use a
+UTF-8 locale. See above (or `examples/docker/postgres-init.sh`) for database
+initialization. You do not need to perform the `database migrate` step.
+
+Next, you need to prepare three files that will be mounted into the travelynx
+container: travelynx configuration, e-mail configuration, and imprint and
+privacy policy. For the sake of this readme, we assume that you are using the
+`local/` directory to store these
+
+* `mkdir local`
+* copy examples/travelynx.conf to local/travelynx.conf and configure it.
+* copy examples/docker/email-transport.sh to local/email-transport.sh and configure it.
+  The travelynx container does not contain a mail server, so it needs a
+  separate SMTP server to send mail. It does not receive mail.
+* create local/imprint.html.ep and enter imprint as well as privacy policy data.
+* create local/terms-of-service.html.ep and enter your terms of service.
+* Configure your web server to reverse-provy requests to the travelynx
+  instance. See `examples/nginx-site` for an nginx config.
+
+travelynx consists of two runtimes: the web application and a background
+worker. Your service supervisor (or docker compose / docker stack / kubernetes
+setup) should orchestrate them somewhere along these lines.
+
+* `docker pull derfnull/travelynx:latest`
+* Start web application: `docker run -p 8093:8093 -v ${PWD}/local:/local:ro travelynx:latest`
+* Wait until localhost:8093 responds to requests
+* Start worker: `docker run -v ${PWD}/local:/local:ro travelynx:latest worker`
+
+To install an update: stop worker and web application, update the travelynx
+image, and start them again. Database migrations will be performed
+automatically. Note that downgrades are not supported.
diff --git a/doc/usage.md b/doc/usage.md
new file mode 100644
index 0000000..2d8bb42
--- /dev/null
+++ b/doc/usage.md
@@ -0,0 +1,34 @@
+# travelynx primer
+
+For the sake of this manual, we will assume your travelynx instance is running
+on `travelynx.de`
+
+travelynx journey logging is based on checkin and checkout actions: You check
+into a train when boarding it, select a destination, and are automatically
+checked out when you arrive. Real-time data is saved on both occasions and
+continuously updated while in transit, providing an accurate overview of both
+scheduled and actual journey times.
+
+## Checking in
+
+You can check into a train at nearly any point in time, though it's usually a
+good idea to do it within a 30-minute window befor/after its departure. The
+precise constraints depend on the selected backend (i.e., data provider).
+
+First, you need to select the stop you want to check in from.  Navigate to
+`travelynx.de` or click/tap on the travelynx text in the navigation bar. You
+will see a list of the five stops closest to your current location (as reported
+by your browser). Select the stop you're at or enter its name manually.
+
+As soon as you select a train, you will be checked in and travelynx will switch
+to the journey / checkout view. If you already know where you're headed, you
+should click/tap on the destination stop in the stop list now. You can change
+the destination by selecting a new one anytime.
+
+## Checking out
+
+You are automatically checked out a few minutes after arrival at your
+destination. If the train has already arrived when you select a destination and
+its arrival was less than two hours ago, you are checked out immediately.  If
+it's more than two hours, you need to perform a manual checkout (without
+arrival data) using the link at the bottom of the checkin menu's stop list.