Andreas/evennia
1
0
Fork 0
mirror of https://github.com/evennia/evennia.git synced 2026-03-31 04:57:16 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Cleaned up Coding and style guides, improved contribs

Browse source
This commit is contained in:
Griatch 2022-11-25 19:47:32 +01:00
parent ce2d001e35
commit a77d568709
30 changed files with 1135 additions and 1360 deletions
Download patch file Download diff file Expand all files Collapse all files

131
docs/source/Setup/Choosing-a-Database.md
View file

@ -10,13 +10,11 @@ This page gives an overview of the supported SQL databases as well as instructio
Since Evennia uses [Django](https://djangoproject.com), most of our notes are based off of what we know from the community and their documentation. While the information below may be useful, you can always find the most up-to-date and "correct" information at Django's [Notes about supported
Databases](https://docs.djangoproject.com/en/dev/ref/databases/#ref-databases) page.
## SQLite3
## SQLite3 (default)
[SQLite3](https://sqlite.org/) is a light weight single-file database. It is our default database
and Evennia will set this up for you automatically if you give no other options. SQLite stores the
database in a single file (`mygame/server/evennia.db3`). This means it's very easy to reset this
database - just delete (or move) that `evennia.db3` file and run `evennia migrate` again! No server process is needed and the administrative overhead and resource consumption is tiny. It is also very fast since it's run in-memory. For the vast majority of Evennia installs it will probably be all
that's ever needed.
[SQLite3](https://sqlite.org/) is a light weight single-file database. It is our default database and Evennia will set this up for you automatically if you give no other options.
SQLite stores the database in a single file (`mygame/server/evennia.db3`). This means it's very easy to reset this database - just delete (or move) that `evennia.db3` file and run `evennia migrate` again! No server process is needed and the administrative overhead and resource consumption is tiny. It is also very fast since it's run in-memory. For the vast majority of Evennia installs it will probably be all that's ever needed.
SQLite will generally be much faster than MySQL/PostgreSQL but its performance comes with two
drawbacks:
@ -44,13 +42,9 @@ To inspect the default Evennia database (once it's been created), go to your gam
This will bring you into the sqlite command line. Use `.help` for instructions and `.quit` to exit.
See [here](https://gist.github.com/vincent178/10889334) for a cheat-sheet of commands.
### Resetting SQLite3 database
### Resetting SQLite3
To reset your database and start from scratch, simply stop Evennia and delete the `mygame/server/evennia.db3`. Then run `evennia migrate` again.
```{sidebar} Hint
Make a copy of the `evennia.db3` file once you created your superuser. When you want to reset, you can just stop evennia and copy that file back over `evennia.db3`. That way you don't have to run migrations and create the superuser every time!
```
If you want to reset your SQLite3 database, see [here](./Updating-Evennia.md#sqlite3-default).
## PostgreSQL
@ -60,14 +54,10 @@ game has an very large database and/or extensive web presence through a separate
### Install and initial setup of PostgreSQL
First, install the posgresql server. Version `9.6` is tested with Evennia. Packages are readily
available for all distributions. You need to also get the `psql` client (this is called `postgresql-
client` on debian-derived systems). Windows/Mac users can [find what they need on the postgresql
download page](https://www.postgresql.org/download/). You should be setting up a password for your
database-superuser (always called `postgres`) when you install.
First, install the posgresql server. Version `9.6` is tested with Evennia. Packages are readily available for all distributions. You need to also get the `psql` client (this is called `postgresql- client` on debian-derived systems). Windows/Mac users can [find what they need on the postgresql download page](https://www.postgresql.org/download/). You should be setting up a password for your database-superuser (always called `postgres`) when you install.
For interaction with Evennia you need to also install `psycopg2` to your Evennia install (`pip
install psycopg2-binary` in your virtualenv). This acts as the python bridge to the database server.
For interaction with Evennia you need to also install `psycopg2` to your Evennia install
(`pip install psycopg2-binary` in your virtualenv). This acts as the python bridge to the database server.
Next, start the postgres client:
@ -104,12 +94,7 @@ GRANT ALL PRIVILEGES ON DATABASE evennia TO evennia;
```
[Here](https://gist.github.com/Kartones/dd3ff5ec5ea238d4c546) is a cheat-sheet for psql commands.
We create a database user 'evennia' and a new database named `evennia` (you can call them whatever
you want though). We then grant the 'evennia' user full privileges to the new database so it can
read/write etc to it.
If you in the future wanted to completely wipe the database, an easy way to do is to log in as the
`postgres` superuser again, then do `DROP DATABASE evennia;`, then `CREATE` and `GRANT` steps above
again to recreate the database and grant privileges.
We create a database user 'evennia' and a new database named `evennia` (you can call them whatever you want though). We then grant the 'evennia' user full privileges to the new database so it can read/write etc to it. If you in the future wanted to completely wipe the database, an easy way to do is to log in as the `postgres` superuser again, then do `DROP DATABASE evennia;`, then `CREATE` and `GRANT` steps above again to recreate the database and grant privileges.
### Evennia PostgreSQL configuration
@ -134,8 +119,7 @@ If you used some other name for the database and user, enter those instead. Run
evennia migrate
to populate your database. Should you ever want to inspect the database directly you can from now on
also use
to populate your database. Should you ever want to inspect the database directly you can from now on also use
evennia dbshell
@ -144,7 +128,11 @@ as a shortcut to get into the postgres command line for the right database and u
With the database setup you should now be able to start start Evennia normally with your new
database.
### Advanced Postgresql Usage (Remote Server)
### Resetting PostgreSQL
If you want to reset your PostgreSQL datbase, see [here](./Updating-Evennia.md#postgresql)
### Advanced PostgreSQL Usage (Remote Server)
```{warning}
@ -153,18 +141,9 @@ database.
an Internet-accessible server.
```
The above discussion is for hosting a local server. In certain configurations
it may make sense host the database on a server remote to the one Evennia is
running on. One example case is where code development may be done on multiple
machines by multiple users. In this configuration, a local data base (such as
SQLite3) is not feasible since all the machines and developers do not have
access to the file.
The above discussion is for hosting a local server. In certain configurations it may make sense host the database on a server remote to the one Evennia is running on. One example case is where code development may be done on multiple machines by multiple users. In this configuration, a local data base (such as SQLite3) is not feasible since all the machines and developers do not have access to the file.
Choose a remote machine to host the database and PostgreSQl server. Follow the
instructions [above](#install-and-initial-setup-of-postgresql) on that server to set up the database.
Depending on distribution, PostgreSQL will only accept connections on the local
machine (localhost). In order to enable remote access, two files need to be
changed.
Choose a remote machine to host the database and PostgreSQl server. Follow the instructions [above](#install-and-initial-setup-of-postgresql) on that server to set up the database. Depending on distribution, PostgreSQL will only accept connections on the local machine (localhost). In order to enable remote access, two files need to be changed.
First, determine which cluster is running your database. Use `pg_lscluster`:
@ -174,10 +153,7 @@ Ver Cluster Port Status Owner Data directory Log file
12 main 5432 online postgres /var/lib/postgresql/12/main /var/log/postgresql/postgresql-12-main.log
```
Next, edit the database's `postgresql.conf`. This is found on Ubuntu systems
in `/etc/postgresql/<ver>/<cluster>`, where `<ver>` and `<cluster>` are
what are reported in the `pg_lscluster` output. So, for the above example,
the file is `/etc/postgresql/12/main/postgresql.conf`.
Next, edit the database's `postgresql.conf`. This is found on Ubuntu systems in `/etc/postgresql/<ver>/<cluster>`, where `<ver>` and `<cluster>` are what are reported in the `pg_lscluster` output. So, for the above example, the file is `/etc/postgresql/12/main/postgresql.conf`.
In this file, look for the line with `listen_addresses`. For example:
@ -205,8 +181,7 @@ on any interface.
for more details.)
```
Finally, modify the `pg_hba.conf` (in the same directory as `postgresql.conf`).
Look for a line with:
Finally, modify the `pg_hba.conf` (in the same directory as `postgresql.conf`). Look for a line with:
```
# IPv4 local connections:
host all all 127.0.0.1/32 md5
@ -226,31 +201,19 @@ Now, restart your cluster:
$ pg_ctlcluster 12 main restart
```
Finally, update the database settings in your Evennia secret_settings.py (as
described [above](#evennia-postgresql-configuration) modifying `SERVER` and
`PORT` to match your server.
Finally, update the database settings in your Evennia secret_settings.py (as described [above](#evennia-postgresql-configuration) modifying `SERVER` and `PORT` to match your server.
Now your Evennia installation should be able to connect and talk with a remote
server.
Now your Evennia installation should be able to connect and talk with a remote server.
## MySQL / MariaDB
[MySQL](https://www.mysql.com/) is a commonly used proprietary database system, on par with
PostgreSQL. There is an open-source alternative called [MariaDB](https://mariadb.org/) that mimics
all functionality and command syntax of the former. So this section covers both.
[MySQL](https://www.mysql.com/) is a commonly used proprietary database system, on par with PostgreSQL. There is an open-source alternative called [MariaDB](https://mariadb.org/) that mimics all functionality and command syntax of the former. So this section covers both.
### Installing and initial setup of MySQL/MariaDB
First, install and setup MariaDB or MySQL for your specific server. Linux users should look for the
`mysql-server` or `mariadb-server` packages for their respective distributions. Windows/Mac users
will find what they need from the [MySQL downloads](https://www.mysql.com/downloads/) or [MariaDB
downloads](https://mariadb.org/download/) pages. You also need the respective database clients
(`mysql`, `mariadb-client`), so you can setup the database itself. When you install the server you
should usually be asked to set up the database root user and password.
First, install and setup MariaDB or MySQL for your specific server. Linux users should look for the `mysql-server` or `mariadb-server` packages for their respective distributions. Windows/Mac users will find what they need from the [MySQL downloads](https://www.mysql.com/downloads/) or [MariaDB downloads](https://mariadb.org/download/) pages. You also need the respective database clients (`mysql`, `mariadb-client`), so you can setup the database itself. When you install the server you should usually be asked to set up the database root user and password.
You will finally also need a Python interface to allow Evennia to talk to the database. Django
recommends the `mysqlclient` one. Install this into the evennia virtualenv with `pip install
mysqlclient`.
You will finally also need a Python interface to allow Evennia to talk to the database. Django recommends the `mysqlclient` one. Install this into the evennia virtualenv with `pip install mysqlclient`.
Start the database client (this is named the same for both mysql and mariadb):
@ -274,27 +237,15 @@ FLUSH PRIVILEGES;
```
[Here](https://gist.github.com/hofmannsven/9164408) is a mysql command cheat sheet.
Above we created a new local user and database (we called both 'evennia' here, you can name them
what you prefer). We set the character set to `utf8` to avoid an issue with prefix character length
that can pop up on some installs otherwise. Next we grant the 'evennia' user all privileges on the
`evennia` database and make sure the privileges are applied. Exiting the client brings us back to
the normal terminal/console.
Above we created a new local user and database (we called both 'evennia' here, you can name them what you prefer). We set the character set to `utf8` to avoid an issue with prefix character length that can pop up on some installs otherwise. Next we grant the 'evennia' user all privileges on the `evennia` database and make sure the privileges are applied. Exiting the client brings us back to the normal terminal/console.
> Note: If you are not using MySQL for anything else you might consider granting the 'evennia' user
full privileges with `GRANT ALL PRIVILEGES ON *.* TO 'evennia'@'localhost';`. If you do, it means
you can use `evennia dbshell` later to connect to mysql, drop your database and re-create it as a
way of easy reset. Without this extra privilege you will be able to drop the database but not re-
create it without first switching to the database-root user.
> If you are not using MySQL for anything else you might consider granting the 'evennia' user full privileges with `GRANT ALL PRIVILEGES ON *.* TO 'evennia'@'localhost';`. If you do, it means you can use `evennia dbshell` later to connect to mysql, drop your database and re-create it as a way of easy reset. Without this extra privilege you will be able to drop the database but not re create it without first switching to the database-root user.
## Add MySQL configuration to Evennia
### Add MySQL/MariaDB configuration to Evennia
To tell Evennia to use your new database you need to edit `mygame/server/conf/settings.py` (or
`secret_settings.py` if you don't want your db info passed around on git repositories).
To tell Evennia to use your new database you need to edit `mygame/server/conf/settings.py` (or `secret_settings.py` if you don't want your db info passed around on git repositories).
> Note: The Django documentation suggests using an external `db.cnf` or other external conf-
formatted file. Evennia users have however found that this leads to problems (see e.g. [issue
#1184](https://git.io/vQdiN)). To avoid trouble we recommend you simply put the configuration in
your settings as below.
> The Django documentation suggests using an external `db.cnf` or other external conf- formatted file. Evennia users have however found that this leads to problems (see e.g. [issue #1184](https://git.io/vQdiN)). To avoid trouble we recommend you simply put the configuration in your settings as below.
```python
#
@ -311,22 +262,24 @@ your settings as below.
}
}
```
The `mysql` backend is used by `MariaDB` as well.
Change this to fit your database setup. Next, run:
evennia migrate
to populate your database. Should you ever want to inspect the database directly you can from now on
also use
to populate your database. Should you ever want to inspect the database directly you can from now on also use
evennia dbshell
as a shortcut to get into the postgres command line for the right database and user.
With the database setup you should now be able to start start Evennia normally with your new
database.
With the database setup you should now be able to start start Evennia normally with your new database.
## Others
### Resetting MySQL/MariaDB
No testing has been performed with Oracle, but it is also supported through Django. There are
community maintained drivers for [MS SQL](https://code.google.com/p/django-mssql/) and possibly a few
others. If you try other databases out, consider expanding this page with instructions.
If you want to reset your MySQL/MariaDB datbase, see [here](./Updating-Evennia.md#mysql-mariadb).
## Other databases
No testing has been performed with Oracle, but it is also supported through Django. There are community maintained drivers for [MS SQL](https://code.google.com/p/django-mssql/) and possibly a few others. If you try other databases out, consider contributing to this page with instructions.

10
docs/source/Setup/Installation.md
View file

@ -4,12 +4,15 @@
If you are converting an existing game from a previous Evennia version, [see here](./Installation-Upgrade.md).
```
The fastest way to install Evennia is to use the `pip` installer that comes with Python (read on).
You can also [clone Evennia from github](./Installation-Git.md) or use [docker](./Installation-Docker.md). Some users have also experimented with [installing Evennia on Android](./Installation-Android.md).
## Requirements
```{sidebar} Develop in isolation
Installing Evennia doesn't make anything visible online. Apart from installation and updating, you can develop your game without any internet connection if you want to.
```
- Evennia requires [Python](https://www.python.org/downloads/) 3.9, 3.10 or 3.11 (recommended)
- Evennia requires [Python](https://www.python.org/downloads/) 3.9, 3.10 or 3.11 (recommended). Any OS that supports Python should work.
- Windows: In the installer, make sure you select `add python to path`. If you have multiple versions of Python installed, use `py` command instead of `python` to have Windows automatically use the latest.
- Using a light-weight [Python virtual environment](./Installation-Git.md#virtualenv) is optional, but _highly recommended_ in order to keep your Evennia installation independent from the system libraries. Using virtualenvs like this is common Python praxis.
- Don't install Evennia as administrator or superuser.
@ -17,9 +20,6 @@ Installing Evennia doesn't make anything visible online. Apart from installation
## Install with `pip`
The fastest way to install Evennia is to use the `pip` installer that comes with Python.
You can also [clone Evennia from github](./Installation-Git.md) or use [docker](./Installation-Docker.md). Some users have also experimented with [installing Evennia on Android](./Installation-Android.md).
Evennia is managed from the terminal (console/Command Prompt on Windows). Once you have Python, you install Evennia with
@ -87,7 +87,7 @@ Full stop of the server (use `evennia start` to restart):
evennia stop
See [Server start-stop-reload](./Start-Stop-Reload.md) page for more details.
See [Server start-stop-reload](./Running-Evennia.md) page for more details.
## See server logs

0
docs/source/Setup/Start-Stop-Reload.md → docs/source/Setup/Running-Evennia.md
View file

5
docs/source/Setup/Setup-Overview.md
View file

@ -14,7 +14,8 @@ Installation-Troubleshooting
Installation-Android
Installation-Upgrade
Installation-Non-Interactive
Start-Stop-Reload
Running-Evennia
Updating-Evennia
```
## Configuration
@ -31,7 +32,7 @@ Channels-to-RSS
Channels-to-Twitter
```
## Going public
## Going Online
```{toctree}
:maxdepth: 2

94
docs/source/Setup/Updating-Evennia.md Normal file
View file

@ -0,0 +1,94 @@
# Updating Evennia
When Evennia is updated to a new version you will usually see it announced in the [Discussion forum](github:discussions) and in the [dev blog](https://www.evennia.com/devblog/index.html). You can also see the changes on [github](github:) or through one of our other [linked pages](../Links.md).
## If you installed with `pip`
If you followed the [normal install instructions](./Installation.md), here's what you do to upgrade:
1. Read the [changelog](../Coding/Changelog.md) to see what changed and if it means you need to make any changes to your game code.
2. If you use a [virtualenv](#Installation-Git#virtualenv), make sure it's active.
3. `cd` to your game dir (e.g. `mygame`)
4. `evennia stop`
5. `pip install --upgrade evennia`
6. `cd` tor your game dir
7. `evennia migrate` (_ignore_ any warnings about running `makemigrations`, it should _not_ be done)
8. `evennia start`
If the upstream changes are large, you may also need to go into your gamedoor
## If you installed with `git`
This applies if you followed the [git-install instructions](./Installation-Git.md). Before Evennia 1.0, this was the only way to install Evennia.
At any time, development is either happening in the `master` branch (latest stable) or `develop` (experimental). Which one is active and 'latest' at a given time depends - after a release, `master` will see most updates, close to a new release, `develop` will usually be the fastest changing.
1. Read the [changelog](../Coding/Changelog.md) to see what changed and if it means you need to make any changes to your game code.
2. If you use a [virtualenv](#Installation-Git#virtualenv), make sure it's active.
3. `cd` to your game dir (e.g. `mygame`)
4. `evennia stop`
5. `cd` to the `evennia` repo folder you cloned during the git installation process.
6. `git pull`
7. `pip install --upgrade -e .` (remember the `.` at the end!)
9. `cd` back to your game dir
10. `evennia migrate` (_ignore_ any warnings about running `makemigrations` , it should _not_ be done)
11. `evennia start`
## If you installed with `docker`
If you followed the [docker installation instructions] you need to pull the latest docker image for the branch you want:
- `docker pull evennia/evennia` (master branch)
- `docker pull evennia/evennia:develop` (experimental `develop` branch)
Then restart your containers.
## Resetting your database
Should you ever want to start over completely from scratch, there is no need to re-download Evennia. You just need to clear your database.
First:
1. `cd` to your game dir (e.g. `mygame`)
2. `evennia stop`
### SQLite3 (default)
```{sidebar} Hint
Make a copy of the `evennia.db3` file once you created your superuser. When you want to reset (and as long as you haven't had to run any new migrations), you can just stop evennia and copy that file back over `evennia.db3`. That way you don't have to run the same migrations and create the superuser every time!
```
3. delete the file `mygame/server/evennia.db3`
4. `evennia migrate`
5. `evennia start`
### PostgreSQL
3. `evennia dbshell` (opens the psql client interface)
```
psql> DROP DATABASE evennia;
psql> exit
```
4. You should now follow the [PostgreSQL install instructions](./Choosing-a-Database.md#postgresql) to create a new evennia database.
5. `evennia migrate`
6. `evennia start`
### MySQL/MariaDB
3. `evennia dbshell` (opens the mysql client interface)
```
mysql> DROP DATABASE evennia;
mysql> exit
```
4. You should now follow the [MySQL install instructions](./Choosing-a-Database.md#mysql-mariadb) to create a new evennia database.
5. `evennia migrate`
6. `evennia start`
### What are database migrations?
If and when an Evennia update modifies the database *schema* (that is, the under-the-hood details as to how data is stored in the database), you must update your existing database correspondingly to match the change. If you don't, the updated Evennia will complain that it cannot read the database properly. Whereas schema changes should become more and more rare as Evennia matures, it may still happen from time to time.
One way one could handle this is to apply the changes manually to your database using the database's command line. This often means adding/removing new tables or fields as well as possibly convert existing data to match what the new Evennia version expects. It should be quite obvious that this quickly becomes cumbersome and error-prone. If your database doesn't contain anything critical yet it's probably easiest to simply reset it and start over rather than to bother converting.
Enter *migrations*. Migrations keeps track of changes in the database schema and applies them automatically for you. Basically, whenever the schema changes we distribute small files called "migrations" with the source. Those tell the system exactly how to implement the change so you don't have to do so manually. When a migration has been added we will tell you so on Evennia's mailing lists and in commit messages - you then just run `evennia migrate` to be up-to-date again.