Skip to main content

​
Quick setup

This guide assumes you’ve completed the Installation steps. We’ll get your Ayase Quart instance running in just a few commands.
1

Activate your virtual environment

source venv/bin/activate
2

Verify configuration

Ensure your config.toml and boards.toml files are properly configured with your database connection and desired boards.Check that your boards are properly set up:
ayaseq prep boards
If successful, you should see ok.
3

Launch the webserver

Start Ayase Quart with Hypercorn:
hypercorn -w 2 -b 127.0.0.1:9001 ayase_quart.main:app
The -w 2 flag specifies 2 worker processes. Adjust based on your server’s capabilities. The -b flag sets the bind address and port.
4

Access your archive

Open your browser and navigate to:
http://127.0.0.1:9001
You should see the Ayase Quart interface with your configured boards!

​
Basic usage

​
Browsing archives

Once your instance is running, you can:
  • View board index - Click on any board to see threads
  • Browse catalog - Switch to catalog view for visual thread browsing
  • Read threads - Click any thread to view full posts and replies
  • Hover over quotelinks - Preview referenced posts inline

​
Searching

Ayase Quart provides two types of search:

​
Moderation

The moderation system requires authentication. The default credentials are:
  • Username: admin
  • Password: admin
Change the default admin credentials immediately in a production environment!
Access moderation features through:
  • Web UI - Cookie-based authentication with math captcha
  • REST API - Bearer token authentication (create token via POST to /api/v1/login)
  • CLI - Direct server access, no authentication needed

​
CLI commands

Ayase Quart includes a CLI for various administrative tasks:

​
Report management

View report count: 
python -m ayase_quart.cli.reports cli-get-report-count
List reports: 
python -m ayase_quart.cli.reports cli-get-reports --public_access v --created_at_gte "2024-01-01"
Take action on reports: 
python -m ayase_quart.cli.reports cli-reports-action \
  --report_parent_id 123 \
  --action report_close \
  --mod_notes "Resolved"

​
Preparation commands

Generate secret key: 
ayaseq prep secret
Update JavaScript integrity hashes: 
ayaseq prep hashjs
Validate boards configuration: 
ayaseq prep boards

​
Search index management

Create search index: 
ayaseq search index create
Load boards into search index: 
ayaseq search load full g v a pol
Reset search index: 
ayaseq search index reset

​
Configuration quick reference

​
Common settings

Key configuration options in config.toml: 
[app]
url = 'http://127.0.0.1:9001'
port = 9001
rate_limiter = true

[site]
name = 'Ayase Quart'
theme = 'tomorrow'
anonymous_username = 'Anonymous'

[archive]
type = 'yotsuba'  # 'yotsuba' (4chan), 'vichan' (lainchan)
canonical_name = '4chan'
canonical_host = 'https://boards.4chan.org'

[vanilla_search]
enabled = true
hits_per_page = 50
max_hits = 1_000

[moderation]
enabled = true

​
Media configuration

Configure how images and thumbnails are served: 
[media]
image_uri = "http://192.168.1.16:9001/static/ritual/{board}/image"
thumb_uri = "http://192.168.1.16:9001/static/ritual/{board}/thumb"
serve_outside_static = false

​
Production deployment

For production use, set up a systemd service: 
[Unit]
Description=Ayase Quart Archive Interface
After=network.target mysql.service redis.service

[Service]
Type=notify
User=your-user
WorkingDirectory=/path/to/ayase-quart
Environment="PATH=/path/to/ayase-quart/venv/bin"
ExecStart=/path/to/ayase-quart/venv/bin/hypercorn -w 2 -b 127.0.0.1:9001 ayase_quart.main:app
Restart=on-failure

[Install]
WantedBy=multi-user.target

​
Updating Ayase Quart

To update your installation:
1

Pull latest changes

git pull --ff origin main
2

Update JavaScript hashes

ayaseq prep hashjs
3

Restart service

sudo systemctl restart ayase-quart
sudo systemctl status ayase-quart
Check if new fields have been added or removed in config.toml after updating. Compare with config.tpl.toml.

​
Troubleshooting

​
Server won’t start

Check that:
  • Your database is accessible
  • Ports aren’t already in use
  • SSL certificates exist (if configured)
  • Config files are valid TOML

​
Database connection errors

MySQL access denied error: 
DROP User 'myuser'@'localhost';
DROP User 'myuser'@'%';
CREATE USER 'myuser'@'%' IDENTIFIED BY 'mypassword';
GRANT ALL PRIVILEGES ON * . * TO 'myuser'@'%';
Then restart MySQL: 
sudo systemctl restart mysql

​
No boards appearing

Verify your boards configuration: 
ayaseq prep boards
Check that your database contains the configured boards.

​
API documentation

Once running, visit /docs on your instance for interactive API documentation: 
http://127.0.0.1:9001/docs
The API supports:
  • Thread and post retrieval
  • Search operations
  • Moderation actions
  • Report management

​
Next steps

Now that your instance is running:
  • Explore the search features
  • Set up full-text search for better performance
  • Configure moderation tools
  • Customize the theme and branding
  • Set up automated backups of your moderation database
  • Configure a reverse proxy (nginx, caddy) for production use
For advanced configuration and plugin development, check the GitHub repository.

Build docs developers (and LLMs) love

Get started for freeTalk to us