Get started
QuillSail documentation
On this page
QuillSail is open-source blog and newsletter software for publications written by their readers. Members submit their writing, editors review it, and the publication goes out on the web and by email from a server you control.
These guides cover everything from trying QuillSail on your own computer to running it for thousands of readers. They’re the same files you’ll find in the repository’s docs/ folder, so they always describe the code next to them.
Start here#
- New to QuillSail? Read how QuillSail works for the main ideas: publications, groups, the editorial workflow and newsletter issues.
- Want to try it? The quickstart takes you from download to a first published post and a test issue in about fifteen minutes.
- Ready to install? Ways to install compares the desktop app, Docker Compose and the Python package.
Common tasks#
| I want to… | Read |
|---|---|
| Install the desktop app with one command | Terminal installer |
| Put my publication online for readers | Server installation |
| Let readers submit writing and review it | Writing and review |
| Send different content to students and alumni | Newsletter issues |
| Decide who can do what | Groups and permissions |
| Send email through Gmail, Outlook or SMTP | Gmail, Outlook and SMTP |
| Make the publication look like ours | Design and themes |
| Update a server safely | Server updates |
| Back up and restore | Backups and upgrades |
| Fix something that isn’t working | Troubleshooting |
Getting help#
QuillSail is beta software maintained on GitHub. Ask questions and report problems in its issues. Report security problems privately, as described in the security policy. Never post passwords, subscriber lists or configuration files in a public issue.
All documentation
Get started
- How QuillSail worksQuillSail runs one publication: a blog, a newsletter, or both. Its readers can become its writers. This page…
- QuickstartThis walk-through takes about fifteen minutes. You’ll install the desktop app, create a publication, take a…
Install
- Ways to installQuillSail runs in three ways. They use the same software and the same data format, so you can start on the…
- Terminal installerInstall the QuillSail desktop app and a quillsail command with one line.
- Desktop appOpen QuillSail to start a local publication and open its dashboard in your browser. The packaged app…
- Server installationQuillSail runs as a Python web application with a persistent database and a background worker. Use Docker…
- ConfigurationQuillSail reads the explicit --config path, then COPYDESK_CONFIG, then ./copydesk.toml, then…
Run a publication
- Publication guideThis guide is for the people who run a publication day to day: administrators, editors and the members who…
- Set up your publicationSign in as the administrator you created during installation, then work through Dashboard → Settings.…
- Groups and permissionsIn QuillSail, groups are both roles and kinds of readers. Editors is a group; so is Alumni. Permissions…
- Writing and reviewMembers write. Editors review. Every piece moves through a clear set of statuses, and both sides can see…
- Blog and newsletter modesA QuillSail publication is a Newsletter, a Blog, or a Blog + newsletter. Hosts choose during browser setup,…
- Newsletter issuesAn issue is one numbered edition of your newsletter. It’s an ordered list of articles, headings and text…
- Subscribers and accountsQuillSail keeps two lists. Subscribers get the newsletter by email and need only an address. Members have…
- CompetitionsRun writing or project competitions with moderated entries, appointed judges, reader voting, deadlines and…
- Business outreach and previewsAdministrators can open Dashboard → Business outreach and enable Accept business inquiries. The /business/…
- Design and themesOpen Settings → Appearance to design the publication without editing files. Start with Classic, Broadsheet,…
- Email and deliveryAdministrators can now connect Gmail or Outlook from Settings → Email. SMTP and configuration-file upload…
- Gmail, Outlook and SMTPAdministrators manage publication email under Settings → Email. Gmail and Outlook are the main options. SMTP…
Operate
- Backups and upgradesAlways back up the configuration (especially its secret key), database, uploaded images, local themes, and…
- Server updatesThe CLI manages the complete update of a registered Linux server: authenticated release download,…
- SecurityThis page explains how QuillSail protects a publication and its readers, and what you need to do when you…
- TroubleshootingStart with the tools QuillSail gives you:
Extend
- ExtensionsCreate extensions/announcements.py beside the instance configuration:
- Public APIThe API lives under /api/v1 (including any configured site prefix). Read routes return JSON and expose…
Reference
- Command lineEvery command starts with quillsail. The older copydesk name still works as an alias. Commands that work on…
- Configuration fileThe configuration file, copydesk.toml, holds what the server needs to run: the public address, the database,…
- Dashboard settingsAdministrators change these under Dashboard → Settings, and they’re stored in the database, so they take…
- Permissions and groupsPermissions belong to groups, and people collect them by joining groups. Everyone, including visitors who…
- Editorial workflowEvery piece of writing has a status. It changes only through the actions below, which check permissions on…
- Extension hooksExtensions are Python modules that create extension = Extension("name") and register hooks on it. Extensions…
Project
- What's newSee verification for the tested scope and remaining limits. Deployment and release-automation files are…
- ArchitectureA guide to the codebase for contributors. QuillSail is a server-rendered Flask application with a…
- ContributingInstall Python 3.11+, create a virtual environment, and run pip install -e '.[dev]'. Run pytest and ruff…
- Releases and GitHubThis repository is prepared for a public MIT-licensed project. Publishing is a separate maintainer action.…
- Signed updatesThe desktop updater uses the maintained python-tuf client. Each package ships a trusted root under…
- Verification recordQuillSail is beta software. These are development checks, not an independent security audit. Private…
- Review notesThis follow-up reviewed access control and failure behavior beyond the initial page-render checks.…
- Security policyDo not put passwords, subscriber exports, email tokens, or production configuration in public issues. Report…
- Code of conductTreat contributors and users with respect. Be constructive when reviewing work, make room for different…