lostplaces-backend/Readme.md

140 lines
7.0 KiB
Markdown
Raw Normal View History

# lostplaces-backend
lostplaces-backend is a django (3.x) based webproject. It once wants to become a software which allows a group of urban explorers to manage, document and share the locations of lost places while not exposing too much / any information to the public.
2020-09-21 21:37:28 +02:00
The software is currently in early development status, neither scope, datamodel(s) nor features are finalized yet. Therefore we would not recommend to download or install this piece of software anywhere - except your local django dev server.
2020-09-21 21:37:28 +02:00
We value privacy as a whole, all resources the frontend requires will be shipped with lostplace's distribution. We also try to minimize the use of JavaScript as far as we can and try to offer JS-less alternatives where we can.
2020-09-10 23:34:24 +02:00
2020-09-10 20:42:43 +02:00
## Features
2020-09-21 21:37:28 +02:00
- Manage lost places with lots of useful information.
2020-09-10 23:34:24 +02:00
- OSM-Maps
2020-09-21 21:37:28 +02:00
- Sensitive information is not accessible for anonymous (not logged in) users.
2020-09-10 22:17:46 +02:00
- User self registration using a voucher system, only people you invite can join your instance.
- Collaboration, every user can add informations like tags, photos and external links to your place.
2020-09-10 20:42:43 +02:00
## Dependencies
2020-07-29 15:25:35 +02:00
Right now it depends on the following non-core Python 3 libraries. These can be installed using the package manager of your distribution or into the venv locally.
2020-09-10 22:17:46 +02:00
* [django](https://www.djangoproject.com/) is a high-level Python Web framework that encourages rapid development and clean, pragmatic design.
* [easy-thumbnails](https://github.com/SmileyChris/easy-thumbnails) A powerful, yet easy to implement thumbnailing application for Django 1.11+.
* [image](https://github.com/francescortiz/image) Image cropping for django.
2020-08-18 14:35:13 +02:00
* [django-widget-tweaks](https://github.com/jazzband/django-widget-tweaks) Tweak the form field rendering in templates, not in python-level form definitions.
* [django-taggit](https://github.com/jazzband/django-taggit) A simpler approach to tagging with Django.
2020-08-20 21:38:35 +02:00
2020-09-10 20:42:43 +02:00
# Installing a development instance
## Clone the repository
`git clone https://git.mowoe.com/reverend/lostplaces-backend.git`
## Setting up a (pipenv) virtual environment for development
After having obtained the repository contents (either via .zip download or git clone), you can easily setup a [pipenv](https://docs.pipenv.org/) virtual environment. The repo provides a Pipfile for easy dependency management that does not mess with your system.
2020-09-10 20:42:43 +02:00
```shell
$ cd lostplaces-backend
$ pipenv install
$ pipenv shell
(lostplaces-backend) $ django_lostplaces/manage.py makemigrations
(lostplaces-backend) $ django_lostplaces/manage.py migrate
(lostplaces-backend) $ django_lostplaces/manage.py createsuperuser
(lostplaces-backend) $ django_lostplaces/manage.py runserver --ipv6
```
2020-09-10 20:42:43 +02:00
## Returning to the venv
```shell
$ cd lostplaces-backend
$ pipenv shell
(lostplaces-backend) $ pipenv update # If dependencies changed, or updates available
(lostplaces-backend) $ django_lostplaces/manage.py makemigrations # If datamodels changed
(lostplaces-backend) $ django_lostplaces/manage.py migrate # If datamodels changed
(lostplaces-backend) $ django_lostplaces/manage.py runserver --ipv6
```
Visit: [admin](http://localhost:8000/admin) for administrative backend or
2020-09-10 22:17:46 +02:00
[frontend](http://localhost:8000/).
Happy developing ;-)
2020-09-10 20:42:43 +02:00
# Installing a productive instance
2020-08-18 14:22:33 +02:00
2020-09-10 20:42:43 +02:00
Currently there are two ways to deploy the lostplaces project:
2020-09-10 22:17:46 +02:00
1. Cloning this repository, including the configured django instance.
2. Install the package and setup the django instance yourself.
2020-08-18 14:22:33 +02:00
2020-09-10 20:42:43 +02:00
## Cloning the repository
2020-08-18 14:22:33 +02:00
2020-09-21 21:37:28 +02:00
Essentially, this is the same as installing a development instance, but without the development server (manage.py runserver) and something powerful (Apache, NGINX) instead. You have to configure the webserver to work with the *SGI Api respectively, reference [django's guide for deployment](https://docs.djangoproject.com/en/3.1/howto/deployment/) for further information.
2020-09-10 20:42:43 +02:00
2020-09-21 21:37:28 +02:00
You also should setup a dedicated database server, the built-in SQLite file is not recommended for production use. Reference [django's guide for databases](https://docs.djangoproject.com/en/3.1/ref/databases/) for further information.
2020-09-10 20:42:43 +02:00
Before making the django instance public, you should tweak the config `settings.py`:
2020-09-10 22:17:46 +02:00
1. Change the secret key, the one found in the config is already public. Choose something secure (i.e. [this](https://duckduckgo.com/?q=password+generator+64)).
2. Turn off debug mode by setting `DEBUG = False`.
3. Tune the localization settings, see [django's documentation](https://docs.djangoproject.com/en/3.1/topics/i18n/).
2020-09-10 20:42:43 +02:00
Run `django_lostplaces/managy.py collectstatic` and you should be ready to go.
2020-09-10 20:42:43 +02:00
## Installing lostplaces to an existing django instance
2020-09-10 20:42:43 +02:00
### Installing django and the django_lostplaces app
2020-09-10 20:42:43 +02:00
2020-09-10 22:17:46 +02:00
If you haven't already setup a django instance, see [django's documentation](https://docs.djangoproject.com/en/3.1/topics/install/).
2020-09-10 20:42:43 +02:00
2020-09-21 21:37:28 +02:00
After that, download the desired release (probably the latest one) [from the releases page](https://git.mowoe.com/reverend/lostplaces-backend/releases) and install it using `pip install --user name-of-the-file.tar.gz`
2020-09-10 20:42:43 +02:00
2020-09-10 22:17:46 +02:00
*Note: You can run pip install without the --user flag, which will require root privileges and introduces potential security issues.*
2020-09-10 20:42:43 +02:00
### Configuring the django instance
Now configure your `settings.py` as follows:
2020-09-10 22:17:46 +02:00
1. Add the following apps to the django project.
2020-09-10 20:46:11 +02:00
2020-09-10 20:42:43 +02:00
```python
2020-08-18 14:24:08 +02:00
INSTALLED_APPS = [
2020-08-18 14:22:33 +02:00
...
'django_lostplaces',
2020-08-18 14:24:08 +02:00
'easy_thumbnails',
'widget_tweaks',
'django_taggit'
2020-08-18 14:24:08 +02:00
]
```
2020-09-10 20:46:11 +02:00
2020-09-10 22:17:46 +02:00
2. Set the URL's and Root-directories for file handling, for example:
2020-09-10 20:46:11 +02:00
2020-09-10 20:42:43 +02:00
```python
STATIC_URL = '/static/'
STATIC_ROOT = os.path.join(BASE_DIR, 'static_files')
2020-08-18 14:22:33 +02:00
2020-09-10 20:42:43 +02:00
MEDIA_URL = '/uploads/'
MEDIA_ROOT = os.path.join(BASE_DIR, 'uploads')
2020-08-18 14:24:08 +02:00
```
2020-09-10 20:46:11 +02:00
3. Set the URL's for login, for example:
2020-09-10 20:46:11 +02:00
2020-09-10 20:42:43 +02:00
```python
2020-08-18 14:24:08 +02:00
LOGIN_URL = reverse_lazy('login')
LOGIN_REDIRECT_URL = reverse_lazy('django_lostplaces_home')
LOGOUT_REDIRECT_URL = reverse_lazy('django_lostplaces_home')
2020-08-18 14:24:08 +02:00
```
2020-08-18 14:22:33 +02:00
2020-09-10 20:42:43 +02:00
### Configuring the URL's
2020-09-21 21:37:28 +02:00
In the `urls.py` configure the `urlpatterns` like this:
2020-09-10 20:42:43 +02:00
```python
2020-08-18 14:24:08 +02:00
urlpatterns = [
2020-09-10 20:42:43 +02:00
path('admin/', admin.site.urls),
2020-09-10 22:17:46 +02:00
path('signup/', SignUpView.as_view(), name='signup'), # If you want to use lostplaces' sign up view.
path('explorers/', include('django.contrib.auth.urls')), # You can change the 'explorers/' to whatever you desire.
path('', include('django_lostplaces.urls')), # In this configuration django_lostplaces will be at the top level of you website, change '' to 'django_lostplaces/', if you don't want this.
2020-09-10 22:17:46 +02:00
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT) # So django can deliver user uploaded files.
2020-08-18 14:24:08 +02:00
```
2020-08-18 14:22:33 +02:00
2020-09-10 20:42:43 +02:00
Before making the django instance public, you should tweak the config `settings.py`:
2020-09-10 22:17:46 +02:00
1. Change the secret key, the one found in the config is already public. Choose something secure (i.e. [this](https://duckduckgo.com/?q=password+generator+64)).
2. Turn off debug mode by setting `DEBUG = False`.
3. Tune the localization settings, see [django's documentation](https://docs.djangoproject.com/en/3.1/topics/i18n/).
2020-09-21 21:37:28 +02:00
4. Set a new (random) SECRET_KEY in settings.py, e. g.: `base64 /dev/urandom | head -c50`
2020-08-18 14:22:33 +02:00
2020-09-21 21:37:28 +02:00
Run `django_lostplaces/manage.py collectstatic` you should be ready to go.