1# Webtiles server
2
3This is the Webtiles server for Dungeon Crawl Stone Soup.
4
5It's a HTTP server that allows users to play DCSS in a web browser.
6
7You can use it for small, personal setups or for large public servers.
8
9## Contents
10
11* [Prerequisites](#prerequisites)
12* [Running the server for testing purposes](#running-the-server-for-testing-purposes)
13* [Running a production server](#running-a-production-server)
14* [Contributing](#contributing)
15
16## Prerequisites
17
18To run the server, you need:
19
20* Linux or macOS (other platforms are untested)
21* Python 2.7 or newer (Python 3.6+ is preferred)
22* The Python dependencies specified in `requirements/`
23* A build of DCSS with webtiles support
24
25You'll need to compile DCSS with `make WEBTILES=y` to get a suitable binary. For
26publicly accessible servers, you should also use `USE_DGAMELAUNCH=y`; this
27disables some things like Wizmode, and enables the milestone and player location
28display in the lobby.
29
30## Running the server for testing purposes
31
321. `cd` to the Crawl source directory
332. Compile Crawl with `make WEBTILES=y`
343. Set up a Python virtualenv:
35
36    ```sh
37    python3 -m virtualenv -p python3 webserver/venv
38    . ./webserver/venv/bin/activate
39    pip install -r webserver/requirements/dev.py3.txt
40    ```
41
424. Run the server: `python webserver/server.py`
43
44    (You need to activate the virtualenv every time you start the server)
45
465. Browse to [localhost:8080](http://localhost:8080/) and you should see the lobby.
47
48When developing, you'll probably want to automatically log in as a
49testing user and disable caching of non-game-data files; see the
50`autologin` and `no_cache` options in webserver/config.py for this.
51
52## Running a production server
53
54Most production servers use [crawl/dgamelaunch-config](https://github.com/crawl/dgamelaunch-config)
55which is a management layer that interacts with the webtiles server and
56dgamelaunch (SSH) service.
57
58Use the requirements files `requirements/base.{py2,py3}.txt`.
59
60The server can be configured by modifying the file `config.py`. Most of
61the options are commented or should be self-evident. Suggestions:
62
63* Set uid and gid to a non-privileged user
64* Enable logging to a file in `logging_config`
65* If required, write a script that initializes  user-specific data, like copying
66  a default rc file if the user doesn't yet have one. You can have the script be
67  run on every login by setting `init_player_program`. There is an example
68  script in `util/webtiles-init-player.sh`, but you will probably want to
69  customise it.
70
71## Contributing
72
73For Python developers, several utilities are available:
74
75* `make format` -- format code
76* `make lint` -- run several Python linters (with Flake8)
77* `tox` -- run tests on all supported Python versions
78* `requirements.in/sync.sh` -- update requirements files
79
80
81### Code Coverage
82
83```sh
84coverage run --source . --omit 'venv/*,*_test.py' -m pytest
85coverage html
86open htmlcov/index.html
87```
88