Build Your First Site¶

This tutorial walks you through creating your first SmallBlock CMS project, setting up the database connection, starting the development server, and publishing your first page. By the end, you’ll have a fully functioning site running locally.

Before You Begin¶

Make sure you have:

Completed the Quick Setup.
Python 3.10+ installed.
A working database (PostgreSQL or MariaDB), with credentials ready.
Access to a terminal or SSH session.

Project Creation Overview¶

The diagram below illustrates the basic workflow for creating a new SmallBlock project:

$digraph G { rankdir=LR; node [shape=box, style="rounded,filled", fillcolor="#eef3f8"]; A [label="Create Project\nsmallblock startproject"]; B [label="Configure Database\nsettings.ini"]; C [label="Run Migrations\nsmallblock migrate"]; D [label="Create Superuser\nsmallblock createsuperuser"]; E [label="Start Dev Server\nsmallblock runserver"]; F [label="Open Admin UI\nhttp://127.0.0.1:8000/admin"]; A -> B -> C -> D -> E -> F; }$

—

Initialize a New Project¶

Use the smallblock CLI tool to create your project directory:

smallblock startproject mysite
cd mysite

This generates the following structure:

mysite/
├── config/
├── static/
├── templates/
├── media/
├── manage.py
└── requirements.txt

Verify

The mysite/ directory exists.
manage.py is present.
templates/ and static/ folders were created automatically.

—

Configure the Database¶

Open config/settings.ini (or your environment file) and configure your database:

[database]
ENGINE = postgresql
NAME = smallblock
USER = sb_user
PASSWORD = your_password
HOST = localhost
PORT = 5432

Notes

Use ENGINE = mariadb if you prefer MariaDB.
HOST may be a container name if using Docker.

Verify

Run:

smallblock check

A successful configuration shows:

Database connection successful.

—

Run the Initial Setup¶

Apply migrations and create your first administrative user:

smallblock migrate
smallblock createsuperuser

Follow the prompts to create a username and password.

Verify

You should see:

All migrations applied successfully.

—

Start the Development Server¶

Start the built-in development server:

smallblock runserver

Then open:

http://127.0.0.1:8000/admin

Verify

The admin dashboard loads.
No database or migration warnings are displayed.

—

Create and Publish Your First Page¶

Open Pages → Add New Page in the admin.
Enter a title, such as Home.
Add some content.
Click Publish.

Your new page is now available at:

http://127.0.0.1:8000/

Verify

You should see your published content rendered using the default theme.

—

Troubleshooting¶

Page not appearing?

Ensure the page is published, not saved as a draft.
Check server logs:
```
smallblock logs
```

Admin site won’t load?

Confirm your database is running.
Re-run migrations:
```
smallblock migrate
```

Server not starting?

Another process may be using port 8000:
```
sudo lsof -i :8000
```

—

Next Steps¶

You now have a working SmallBlock CMS installation.

Continue building your skills by exploring:

Create a Plugin — extend the CMS with Python modules.
Extend the Toolbar — add tools to the editor UI.
Using Template Tags — insert dynamic data into templates.
Building a Custom Theme — create your own site design.
Production Deployment — prepare your project for live hosting.