This repository provides a production-ready setup of Misago for people who:
- Want to run their own forum using Misago.
- Have a server with 1GB of RAM and Docker available.
- Have basic knowledge of Linux to SSH to a VPS, navigate the file system, modify files, run programs, and follow instructions from guides.
It sets up Misago forum running on Python 3.12 behind an NGINX reverse proxy with HTTPS enabled using Let's Encrypt. It uses PostgreSQL for the database and Redis for caching and messaging. Celery is included for task queue functionality.
To help you with running your site, the repository includes a tool called appctl that provides shortcuts for common actions and wizards for configuration management, eliminating the need for manual file editing.
Note for DevOps pros: This repository assumes that users will clone it onto their servers using git clone, run ./appctl setup for basic configuration, and run all necessary services in Docker Compose with data stored on the server using Docker volumes. This approach is compatible with setups where services run on dedicated instances or services like Amazon S3 or RDS. The goal of this repository is to make Misago a viable option for hobbyists and small/medium communities, rather than enterprise deployments that require massive scalability to serve a large number of active users simultaneously.
For a complete step-by-step setup guide, please refer to the documentation.
To start your own Misago site, you will need:
- A server running Linux with Docker, Compose plugin and at least 1GB of memory (DigitalOcean droplets are a recommended option).
- A domain configured to point to your server.
ssh to your server. If you are on Windows, you can use PuTTY. Next, clone this repo using the following command:
git clone https://github.com/rafalp/misago_docker.git --depth=1
This will create misago_docker directory that you can then cd to and continue site setup.
Enter the misago_docker directory and run ./appctl setup command. The wizard will let you set basic settings for your site: your domain name, timezone or first admin account details. After that it will:
- Install all the requirements.
- Build Docker containers.
- Setup
crontabthat will run daily maintenance. - Create database and populate it with initial data.
When setup finishes, visit your domain in order to see your Misago forum running.
Lastly, go to https://yourdomain.com/admincp/ and log into the admin panel using the username and password you entered during the setup. There you will be able to further configure your forum. For instance: set forum name, create categories and such.
Depending on initial configuration of your server, you may have to take additional steps to make it more secure. Internet is patrolled by bots searching for vulnerable servers attempting to brute-force root accounts so you should disable the root login, block IP addresses upon repeated failed authentication attempts, or both. You can easilly enable 10-minute ban for 3 failed sign-in entries by installing fail2ban:
apt-get install fail2ban
If you haven't done so during installation, you really should enable e-mails on your site. Not enabling e-mails doesn't mean that Misago will fallback to some other messaging mechanism. It will simply discard all messages without attempting to connect to any e-mail sending service.
Without e-mails enabled your users will not be able to receive activation e-mails, notifications, confirm password changes or reset forgotten passwords.
You can also create account on Sentry (https://sentry.io) and enable it on your site using ./appctl sentry. Sentry provides fancy web interface for browsing Misago's logs, and will send you e-mail with notifications when your users experience errors or edit their profile details, which is possible source of forum spam.
Misago uses Redis for caching and tasks queue. To get most performance out of it, you will have to make sure that you have Transparent Huge Pages (THP) support disabled in your kernel. To do that run the command echo never > /sys/kernel/mm/transparent_hugepage/enabled as root, and add it to your /etc/rc.local in order to retain the setting after a reboot. Docker Redis container must be restarted after THP is disabled, but you can simply run ./appctl restart for same effect.
To upgrade to newer version, go to misago_docker directory and run ./apctl upgrade. This will backup your data, get latest code from github, rebuild Docker containers and update Misago (and other services) to latest minor releases.
You may have to setup git credentials on your machine for git pull to work, but entering git password is not required.
Running the ./appctl backup will result in new backup being created in backups directory.
Backup will be a tar.gz archive named following the manual-YYYYMMDDHHMMSS.tar.gz format and will contain database.sql file with database export created using pg_dump, and media directory containing user-uploaded files.
You can restore your site's data by placing the backup archive in the backups directory, and running ./appctl restore yourbackupfile.tar.gz. If your backup file is located in the subdirectory, you can specify the path to it relative to backups, eg.: ./appctl restore 2018/10/yourbackupfile.tar.gz.
Restoration will:
- overwrite your current
mediadirectory with one from archive. - load the
database.sqltopsql, overwriting existing database tables with ones from file.
NOTE: because restoration process can be considered destructive, you should backup existing data if you are restoring the site that has any data you may want to recover if something goes wrong.
After you've restored from backup, it's good idea to follow up with ./appctl rebuild to rebuild Misago image, giving it's application container a chance to rebuild filesystem caches.
./appctl adds daily backup to system cron. This backup is ran before all other maintenance tasks, providing fallback point in case that maintenance deletes something you really didn't want to delete. Automatic backup files start with auto- and are deleted automatically after 10 days.
You can create your own backup archives for use with ./appctl restore.
Start off with creating a directory, mybackup for instance. Create the following files and directories inside of it:
database.sql - PostgreSQL dump that can be imported with psql.
media - your forum's media directory.
Your ready backup should look like this:
mybackup
- media
- database.sql
Now run tar -zcf mybackup.tar.gz mybackup. This will produce the mybackup.tar.gz file that you can put in backups directory and restore with ./appctl restore mybackup.tar.gz.
Inside misago/theme directory you will find two folders that allow you to customise your site's looks:
static for overriding/adding static files such as css, js, images or fonts.
templates for overriding Django templates with custom ones.
You may want to use themes feature available in admin control panel instead.
Let's say you've cloned main repo to your dev machine. Got it running and customised the CSS to make your site's theme dark instead of default. You've ran build script and got final misago.css file containing your changes. How do you now deploy this file to production?
First, you need to find out the path of the original file relative to its static directory. In case of Misago this is static/misago/css/misago.css. This means that to make Misago use your file instead of default, it should be deployed to theme/static/misago/css/misago.css original.
After deploying your new file, run ./appctl collectstatic to make Misago "collect" this file and replace default with it.
If you are familiar with Python/Django applications or Docker images involved and wish to customise your setup further, please feel free to branch off/fork the repo - it's simple enough that merging eventual changes from upstream shouldn't be much of an issue.
To override configuration in docker-compose.yml, create docker-compose.override.yml file next to it, and re-define selected parts in it. For example, to change default HTTP for NGINX proxy from 80 to 8080, you can include following configuration in your override:
version: '3.0'
services:
nginx-proxy:
ports:
- "8080:80"To add or change settings defined in settings.py that don't support change via environment variable, you can create additional file settings_override.py next to it:
SESSION_COOKIE_NAME = "myforumsid"To add custom urls to the site, create urls_override.py file that contains custom urlpatterns:
from django.conf.urls import include
urlpatterns = [
url(r"^my-app/", include("myapp.urls")),
]Because urlpatterns defined in override are checked before default ones, this approach supports overriding already-existing urls.
Contains backups created by ./appctl backup and loadable by ./appctl restore BACKUPNAME.
This directory contains configuration for Misago and PostgreSQL containers as well as Nginx config.
Log files created by Misago container. If you are experiencing errors, see misago.log or uwsgi.log file contents for complete error message together with backtrace.
Defines Docker container for Misago complete with UWSGI server running Misago and serving its static files.
Extends jwilder/nginx-proxy Docker image to disable TLSv1.0 https encryption on your site, improving it's security rating.
Python scripts that ./appctl runs when it needs to create or change .env files with configuration.
Docker overhead on CPU and memory is negligible, but same can't be said about its disk usage. ./appctl tries to cleanup whenever possible, but to be safe you will have to monitor amount of free space left on your server, and clean up once in a while using commands like docker compose image prune, manually emptying older logs and backups stored in logs and backups directories.
Default cron task will also try to delete log files older than 60 days.
If you have problems setting up your site using misago_docker, feel free to ask on our forums or Discord Chat. Please don't use Github issues!
If you've found a bug, issue, or place for improvement, please open an issue or pull request.
This is free software and you are welcome to modify and redistribute it under the conditions described in the license. For the complete license, refer to LICENSE.