Version 7.15
A small, beautiful and fast wiki-like site for Dimmu Saurus, that works equally good on a powerful PC and on an old Nokia running Opera Mini.
Visit http://dimmu-saurus.net.
The project runs in a bash-compatible terminal. If you are going to write any code, check the contributing guide after you are done with the setup.
- Apache 2.4 + mod_wsgi (production only)
- nodejs 14.18+ (development only; 16.11+ recommended)
- Python 3 (3.8, 3.9 or 3.10)
- sqlite 3.8.3+ (3.31+ recommended; it is usually included with Python, but you may need to install it manually)
- Pip 3
- markdown2 python package. Required for converting any database markdown content to HTML. (Your Python version may include it by default. Install with
$ pip install -r requirements.txt
.) - Django 4.0+ (Install with
$ pip install -r requirements.txt
; Latest 4.x recommended)- If you have several Django apps, you'd want to install it in a
virtualenv
. Check out Django docs how to do this. - gettext 0.15+. (It is available by default in major Linux distributions, but if you don't have it, or you are using a different OS, you need to install it.)
- If you have several Django apps, you'd want to install it in a
For Debian 11, there is a script that can install everything automatically. Check Deployment for details.
As per Django docs, you must set host and port, before running. Installation scripts take care of this automatically, but if you are running locally, or need to do it manually, keep reading.
To change settings:
$ cd src/py/
- Open
pysaurus/settings.py
and setSITE_HOST
,SITE_PORT
andBASE_URL
properly.SITE_HOST
is either an IP address, or a domain name only. Nohttp(s)://
.SITE_PORT
is an empty string by default. Leave it blank unless the site is going to be accessed at a non-standard port, for examplesome-domain.com:3666
.BASE_URL
is used for generating absolute URLs in templates.
The project runs on Sqlite3 that comes with Python, so there is no need to install anything extra. Normally, you do not need to take care the database at all, as Django and the build-tools do it for you, but should you need to do so, run: sqlite3 src/py/db.sqlite3
.
There are $ make db-backup
and $ make db-import
commands, for exporting and importing the data. They generate and read a .tar
containing .csv
, respectively. Each .csv
inside the tarball corresponds to a database table and is compatible with sqlite3. See more about the make commands below.
Warning: db-import
will truncate each table before importing the corresponding .csv
data! Tables not matching a .csv
file, however, will not be affected.
A note on importing backups with the make command: have in mind that exporting appends the current date and time to the filename, however, make db-import
expects and reads ONLY a ds.db.tar
file from db/
directory. If you require flexibility, use the db-import.sh
script directly.
This section is for running the site locally.
$ make django
$ cd dist/py/
$ python3 manage.py runserver [a-port-of-your-choice]
The site will be available on 127.0.0.1:8000, or at the port you have chosen.
$ make ui
$ cd dist/
- Open the
index.html
or run$ make serve-ui
and openlocalhost:3000
.
This website is intended to run on a Debian 11 server. There is a setup-debian11.sh
script for installing all the required software and setup-project.sh
for installing the site itself. Historically it used to run on Ubuntu Server 16.04, so there is a script for setting it up, however, many packages in that distribution are outdated, so using it is not recommended.
If you choose another distribution, you will have to install all requirements manually. setup-project.sh
should work with minimal changes in the Apache setup section.
Note about the content: As a security measure, the intended workflow is to have an admin account locally and use db-backup
and db-import
make commands to transfer the database to a remote server. In case you choose to manage the database on the remote machine, just create an admin account there instead of locally, and skip database steps from the instructions below.
In both cases, follow Django Docs to create the admin account.
Make sure to create a user with root privileges. You are going to need one (but not the "root" superuser) to install the website. Follow this guide.
To create an installation archive, and export your local database, run locally:
$ make tar && make db-backup
Now copy the tarball and the database backup from db
directory to the remote server.
The setup script is assumed to run on a brand new server that doesn't have anything installed. It will install or replace Apache, mod_wsgi, Python 3.9.
- ssh to your server, making sure you are not "root".
$ mkdir upload && tar xvf ds.tar.bz2 -C upload/ && cd upload
to extract the tarball$ sudo ./setup-debian11.sh
to install all requirements (or do it manually on other distributions).$ ./setup-project.sh --all
to install the site itself. It will prompt where to put the site and what hostname and port it will run on. You may leave them blank and use the defaults.$ ./db-import.sh database-backup-name.tar target-database.sqlite3
to import the data into Sqlite.- Ensure the project directory and its parent(s) have the executable flag, otherwise Apache will not able to access them. The
setup-project.sh
script takes care of the website itself, but you may want to double check the parent directory in case you get403 Forbidden
, when you try to access the site.
That's it! Now open it in your browser.
If you are going to enable HTTPS with certbot, be aware there is a known incompatibility between it and Python WSGI definitions in Apache virtual hosts.
- Go to the directory where your Apache virtual hosts are (for example: /etc/apache2/sites-available/).
- Comment out all the "WSGI..." lines in the virtual host file.
- Run
[sudo] certbot --apache -d dimmu-saurus.net
normally. - Uncomment the "WSGI..." lines in the autogenerated
xxxxx-le-ssl.conf
virtual host file (for https/port 443) and keep them commented in the standard file (for http/port 80). - Restart Apache.
- Go to the directory where your Apache virtual hosts are (for example:
/etc/apache2/sites-available/
). - Comment out all the "WSGI..." lines in the HTTP
.conf
file. - Delete the HTTPS
.conf
file (the one named:xxxxx-le-ssl.conf
). - Run
[sudo] certbot --apache
normally. - Uncomment the "WSGI..." lines in the autogenerated
xxxxx-le-ssl.conf
virtual host file (for https/port 443) and keep them commented in the standard file (for http/port 80). - Restart Apache.
In case you need to build only a part of the project, or work with the database, the following commands are available:
$ make clean
: cleans up thedist
folder.$ make css
: compiles all css into one file, minifies it, then copies it to the Djangostatic
folder.$ make js
: same as$ make css
but for javascript.$ make django-static
: copiespy
source code and translations, builds thecss
andjs
, copies the images to Djangostatic
folder. This is the default target. Important: This commands creates a link to the database insrc/py/
, not a copy, so making any changes to the data will affect the original file.$ make translations
: generates or updates .po translation files from python source code. Same as running:$ django-admin makemessages
command.$ make django
: Runs all the above, but also installing all requirements, making sure the site will run properly.
$ make clean
: cleans up thedist/
folder.$ make css-debug
: compiles all css into one file without minifying it.$ make images
: images don't need building, so they are just copied.$ make js-debug
: same as$ make css-debug
, but for JavaScript.$ make ui
: runs all the above to build the frontend demo, including copying the necessary.html
files.
$ make db-backup
: exports the data from all content tables to.csv
files, one per each table, then packs them in a.tar
. The resulting tarball will be indb/
directory. Date and time will be appended to the filename, so it is safe to run it multiple times. No backups will be overwritten.$ make db-import
: Looks for a file namedds.db.tar
in thedb/
directory, created using$ make db-backup
(Note the tarball filenames!). If the file is found, for each.csv
in the tarball, it truncates the corresponding table in the database, then inserts the new data. Unrelated tables will not be affected.$ make tar
: builds the django site (including images), then makes a compressed tarball out of it. Also, includes necessary install scripts. Check Deployment for more info.
The source code and the logo image are licensed under the conditions described in LICENSE.txt. "Griffy" font is under SIL Open font license. "Noto Sans" font is licensed under Apache License 2.0. All other libraries are under the respective licenses provided with their source code.