wish/README.md

LEdoian's Wish
====

This is a simple Django project to create and share lists of wishes. There are two motivations for this project:

1. Christmas. Every time anybody asks me what I want for Christmas, I am totally unable to answer that.
2. The need to test various Django extensions and features before production deployment.

Also: Simple TODO lists. They are lists anyway, so reusing this project seems
fine. But they will only work as a plain list, no special features.

Contributing and support
---
Code lives at <https://gitea.ledoian.cz/LEdoian/Wish>
Send questions and patches to <mailto:wishpatch@pokemon.ledoian.cz>

Currently there is no documentation :-/

Installing
---

### Prerequisities

Psycopg2 needs PostgreSQL client library to be installed. On Debian, the package is `libpq-dev`.

### Installation

1. Pull the repository to preferred location (`git clone
   https://gitea.ledoian.cz/LEdoian/Wish.git <location>` should be sufficient).
2. Optionally create a virtualenv (the deployment script and example
   configuration expect it in `venv` directory at repo root).
3. Install the requirements
4. Tweak and deploy the settings:
	- Instance configuration template is in `conf/deploycfg.py` and should be
	  placed in `$XDG_CONFIG_DIR/wish/deploycfg.py` (or
	  `~/.config/wish/deploycfg.py` if `$XDG_CONFIG_DIR` is not set). Tweak to
	  your needs according to [Django
	  documentation](https://docs.djangoproject.com/en/4.0/ref/settings/).
	- Configure a web reverse proxy and WSGI server to your liking. The `conf`
	  directory contains example configuration files for uWSGI, nginx and
	  systemd.
5. Verify the configuration using `./manage.py check --deploy`. If there are
   relevant errors, tweak the configuration more.
6. If everything seems OK, start the systemd service and try reaching the site.
7. You will need a superuser to be able to add other users and use the admin
   site: `./manage.py createsuperuser`

You will likely need to reference documentation of Django, uWSGI (or other WSGI
server implementation), web reverse proxy of your liking and your service manager.

If you deploy using git, have a virtualenv in `./venv/` and use systemd to run
the service, you can try to use the provided script `./deploy.sh` for
subsequent deploys. Keep in mind, however, that it is written so it WorksForMe™
and I do not guarantee that it will work for you. But I might be able to help
you and/or am open to changes, so feel free to send me questions and/or patches.

Known bug: If the deployment script is itself modified, it will not reexecute
itself unless changing git branches. However, it will likely run past `git
pull`, so re-running should run the updated version.

Licence
---
The _code_ is distributed under WTFPL v2.0. On the other hand, documentation
(including this readme) is not; its licence is not yet decided.

Parts of the code are autogenerated by
[Django](https://www.djangoproject.com/), not by me. IANAL, so I cannot tell
the specific condition of sharing this code. (However, they do not seem to care
about those bits…)

### Rationale

I would like to promote free software and especially empower any user of the
software to be able to access the source code. Therefore, I _recommend_ anyone
to link to the source code.

However, this is a playground for my experiments with Django that I might want
to copy-paste to other projects, without worries. I also want to make sure that
others can do the same, since there probably will be nothing special in the
code, just some tricks that may actually work.

I _might_ want to change the licence in the future. It will _probably_ be
permissive, too.

The documentation in this project, however, feels a lot like an original work,
so it should get a reasonable licence with reasonable conditions (i.e. at least
something like CC BY, probably stricter). I still want anyone to be able to
read and contribute the docs, but it should not get easily stealable.