add README & LICENSE

1 files changed, 96 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fb0d872
--- /dev/null
+++ b/README.md
@@ -0,0 +1,96 @@
+Fietsboek
+=========
+
+Fietsboek is a self-hostable sharing site for GPX track recordings with social
+features. The goal is to have an application like [MyTourbook][MyTourbook] that
+runs as a web-service and allows sharing and discovering of new tracks.
+
+Note that Fietsboek is early in development and a hobby project, as such many
+features are still lacking.
+
+[MyTourbook]: https://mytourbook.sourceforge.io/mytourbook/
+
+Installation
+------------
+
+- Generate a fresh virtual environment (recommended):
+
+      virtualenv .venv
+
+- Install `fietsboek`:
+
+      .venv/bin/pip install .
+
+- (Optionally: Install `lxml` to speed up GPX parsing)
+
+      .venv/bin/pip install lxml
+
+- Adjust `production.ini` to your needs, mainly check the following settings:
+
+      sqlalchemy.url - see https://docs.sqlalchemy.org/en/14/core/engines.html#database-urls
+      session_key - set this to a random secret which is used to sign session keys
+      available_locales - set this to the list of locales you want to support
+                          (by default, English and German translations are shipped)
+      enable_account_registration - whether users should be able to create new accounts
+                                    (set this to false for a private instance)
+      pyramid.default_locale_name - set the default language
+      email.from - the address that Fietsboek email's will be sent from
+      email.smtp_url - the URL of the SMTP server to send emails
+                       (smtp://host:port, smtp+ssl://host:port, smtp+starttls://host:port)
+      email.smtp_user, email.smtp_password - SMTP login information
+
+- Create the database tables:
+
+      .venv/bin/alembic -c production.ini upgrade head
+
+- Start Fietsboek:
+
+      .venv/bin/pserve production.ini
+
+This runs Fietsboek using Pyramid's [Waitress](https://docs.pylonsproject.org/projects/waitress/en/stable/index.html)
+server. If you need a better performance, read [the corresponding
+section](https://docs.pylonsproject.org/projects/waitress/en/stable/index.html)
+in the Pyramid documentation and set up Fietsboek using an alternative server,
+such as `gunicorn` or `mod_wsgi`.
+
+Note that it is advised to use a reverse proxy in front of Fietsboek to handle
+SSL. **Not setting up a SSL capable reverse proxy puts the security of your
+users at risk!**
+
+Development
+-----------
+
+- Setup the environment:
+
+      virtualenv .venv
+      .venv/bin/pip install -e '.[testing]'
+
+- Adjust `development.ini` to your needs
+- Initialize the database:
+
+      .venv/bin/alembic -c development.ini updgrade head
+- Serve the code:
+
+      .venv/bin/pserve development.ini --reload
+
+- Hack away!
+
+License
+-------
+
+    Fietsboek, the GPX web sharing project
+    Copyright (C) 2022 Daniel Schadt
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+