This code runs https://www.themotte.org .

Installation (Windows/Linux/MacOS)

1 - Install a container runtime and the Docker commandline tools on your machine.

On Windows, Docker will pester you to pay them money for licensing. If you want something less proprietary, consider Container Desktop or Stevedore instead.

2 - Install Git. If you're on Windows and want a GUI, Github Desktop is quite nice.

3 - Run the following commands in the terminal or command line for first-time setup:

git clone https://github.com/themotte/rDrama/

cd rDrama

4 - Run the following command to start the site:

docker-compose up --build

The first time you do this, it will take a while. It'll be (much) faster next time.

4 - That's it! Visit localhost in your browser.

Code edits will be reflected (almost) immediately. If you make any setup changes or database changes, you'll need to ctrl-C the docker-compose status log and run docker-compose up --build again.

Run the E2E tests:

./util/test.py

Database Stuff

What is a migration?

Prior to the fork of themotte from rDrama, there were no database migrations, and the database schema was stored in schema.sql. Any time a column or such was added to a model, one hoped that the author remembered to update schema.sql to add that column. One of the first changes we made after forking this repo was to add database migrations using Alembic.

Database migrations are instructions for how to convert an out-of-date database into an up-to-date database. This can involve changing the schema, or changing data within the database.

Why use database migrations

Database migrations allow us to specify where data moves when there are schema changes. This is important when we're live -- if we rename the comments.ban_reason column to comments.reason_banned for naming consistency or whatever, and we do this by dropping the ban_reason column and adding a reason_banned column, we will lose all user data in that column. We don't want to do this. With migrations, we could instead specify that the operation in question should be a column rename, or, if the database engine does not support renaming columns, that we should do a three-step process of "add new column, migrate data over, drop old column".

Database schema change workflow

As an example, let's say we want to add a column is_flagged to the comments table.

1. Update the Comment model in files/classes/comment.py

	from files.__main__ import Base
	class Comment(Base):
		__tablename__ = "comments"
		id = Column(Integer, primary_key=True)
		...
+		is_flagged = Column(Boolean, default=False, nullable=False)

2. Autogenerate a migration with a descriptive message. To do this, run

./util/command.py db revision --autogenerate --message="add is_flagged field to comments"

This will create a migration in the migrations/versions directory with a name like migrations/versions/2022_05_23_05_38_40_9c27db0b3918_add_is_flagged_field_to_comments.py and content like

"""add is_flagged field to comments
Revision ID: 9c27db0b3918
Revises: 16d6335dd9a3
Create Date: 2022-05-23 05:38:40.398762+00:00
"""
from alembic import op
import sqlalchemy as sa
# revision identifiers, used by Alembic.
revision = '9c27db0b3918'
down_revision = '16d6335dd9a3'
branch_labels = None
depends_on = None
def upgrade():
    op.add_column('comments', sa.Column('is_flagged', sa.Boolean(), nullable=False))
def downgrade():
    op.drop_column('comments', 'is_flagged')

3. Examine the autogenerated migration to make sure that everything looks right (it adds the column you expected it to add and nothing else, all constraints are named, etc.) If you see a None in one of the alembic operations, e.g. op.create_foreign_key_something(None, 'usernotes', 'users', ['author_id']), please replace it with a descriptive string before you commit the migration.

4. Restart the Docker container to make sure it works.

docker-compose up --build

So what's up with schema.sql, can I just change that?

No, please do not do that. Instead, please make a migration as described above.