diff --git a/README.md b/README.md
index 29e206a..f845c4a 100644
--- a/README.md
+++ b/README.md
@@ -9,3 +9,69 @@ To login a user should be manually created by running the following commands in
     from django.contrib.auth.models import User
     user = User.objects.create_user('<USERNAME>', '<EMAIL>', '<PASSWORD>')
     user.save()
+
+## Running the project
+
+This project uses Django. The instructions below show how to run the site in a local/testing (development) mode and a simple release (production) mode. All commands assume you're in the repository root.
+
+- Create and activate a virtualenv (recommended):
+
+    .venv/bin/python -m venv .venv
+    source .venv/bin/activate
+
+- Install dependencies:
+
+    pip install -r requirements.txt
+
+- Configure environment variables in a `.env` file (the app reads `GALLERY_ROOT` and `THUMBNAILS_ROOT`). Example `.env` contents:
+
+    GALLERY_ROOT=/path/to/images
+    THUMBNAILS_ROOT=/path/to/thumb-cache
+
+Development / testing mode
+
+- Apply migrations and run the development server:
+
+    .venv/bin/python manage.py migrate
+    .venv/bin/python manage.py runserver
+
+This runs Django's built-in development server (DEBUG mode). It's suitable for local testing and development only.
+
+Release / production mode (simple guide)
+
+- Collect static files and run with a WSGI server like `gunicorn` (example):
+
+    .venv/bin/python manage.py collectstatic --noinput
+    GALLERY_ROOT=/path/to/images THUMBNAILS_ROOT=/path/to/thumb-cache \
+      gunicorn NibasaViewer.wsgi:application --bind 0.0.0.0:8000 --workers 3
+
+Set `DEBUG=False` and provide a proper `ALLOWED_HOSTS` value in your environment or settings when running in production. Use a reverse proxy (nginx) for serving static files and handling HTTPS in front of your WSGI server.
+
+Running tests
+
+- Run the full Django test suite:
+
+    .venv/bin/python manage.py test
+
+- Useful focused test commands (fast iteration):
+
+    .venv/bin/python manage.py test viewer.test
+    .venv/bin/python manage.py test viewer.test.GalleryViewTests
+    .venv/bin/python manage.py test viewer.test.GalleryViewTests.test_search_action_url_uses_nested_path
+
+- Sanity checks recommended before pushing changes:
+
+    .venv/bin/python manage.py check
+    .venv/bin/python manage.py makemigrations --check --dry-run
+    .venv/bin/python -m compileall NibasaViewer viewer
+
+Other useful management commands
+
+- Pre-generate thumbnails (batch):
+
+    .venv/bin/python manage.py makethumbnails
+
+Notes
+
+- Keep `.env` local and out of version control; use `.env.example` as a template if you want to commit a sample file.
+- For production deployments follow standard Django deployment guides (use a dedicated WSGI server, reverse proxy, secure secret management, and proper file permissions).