Everything you need to run Inkwell.

Overview

Inkwell is a free, open-source, self-hosted blogging platform built on .NET 10. It is a single ASP.NET Core application that runs on the .NET 10 runtime — no PHP, and no Node to build or run it (the compiled CSS ships in the repository). Install it on any server you control, point a domain at it, and write.

Core concepts

• Deployment mode — SelfHosted (the default) runs a single-owner install; Cloud serves many blogs from one install, each tenant isolated by its URL slug. Set with the DeploymentMode key.
• Layouts — 20 structural templates, including Magazine, Feed, Catalog, Verdict, Grid, Minimal, Neutral, Classic and Modern.
• Presets — 16 colour presets, swappable from the admin panel without touching content.
• Editor — a Quill WYSIWYG editor to compose visually, draft, schedule and publish, or write any post or page in Markdown with a server-rendered preview. Every saved change is kept as a revision you can compare and restore.
• Data access — Dapper with raw SQL on SQL Server. No ORM, and the schema applies itself on startup.

Requirements

Installation

1. Clone the repository

$ git clone https://github.com/marutisoftwaresolutions/inkwell
$ cd inkwell

2. Restore packages

$ dotnet restore Blog.slnx

3. Configure (see Configuration)

Copy the example settings file and set your connection string:

$ cp Blog.Web/appsettings.example.json Blog.Web/appsettings.json

4. Run

$ dotnet run --project Blog.Web

There is no separate migration step. On first launch, Inkwell’s MigrationService creates every table and seeds the default roles, and it re-applies any new schema on each startup.

Quick start

The fastest path to a running instance, once a connection string is set (see Database):

$ git clone https://github.com/marutisoftwaresolutions/inkwell
$ cd inkwell
$ dotnet run --project Blog.Web

For a complete stack with SQL Server and automatic HTTPS, use Docker Compose instead.

Configuration

Settings live in Blog.Web/appsettings.json, copied from appsettings.example.json. Any key can be overridden with an environment variable using the double-underscore convention: ConnectionStrings:DefaultConnection becomes ConnectionStrings__DefaultConnection.

Configuration reference

Multi-tenant setup

Inkwell supports two deployment modes, chosen with a single key:

{
  "DeploymentMode": "Cloud"
}

• SelfHosted (default) — a single-owner install. The first admin owns the site.
• Cloud — one install serves many blogs, and each tenant is resolved and isolated by its URL slug.

Layout, Preset and CSS variable overrides are chosen per tenant from the admin panel, not in the settings file.

Database

Inkwell runs on Microsoft SQL Server — SQL Server 2019 or later, or SQL Server LocalDB — through Dapper with raw SQL. It is the only supported database.

{
  "ConnectionStrings": {
    "DefaultConnection": "Server=.;Database=inkwell;User Id=sa;Password=yourpass;TrustServerCertificate=True;"
  }
}

Schema changes ship as idempotent, dated scripts in DBScripts/ and are applied automatically on startup. To apply them by hand, always pass -f 65001 so NVARCHAR text keeps its encoding:

$ sqlcmd -S <server> -d <db> -U <user> -P <pass> -f 65001 -i "DBScripts\init.sql"

Email (SMTP)

Used for password reset, subscriber confirmation, error alerts, and sending newsletters. SMTP is optional: without it, password reset and error-alert email are simply unavailable and the rest of the site keeps working. Newsletter issues go out in the background in batches of Newsletter:BatchSize per minute, with retries, so a large list never blocks the site. Newsletter sending is available on single-site installs, not in Cloud mode.

Layouts & Presets

Inkwell separates structure (Layout) from surface (Preset). Pick one of each from the admin panel. Swap them without a rebuild or a migration.

Layouts

Inkwell ships 20 Layouts: Almanac, Bento, Broadsheet, Catalog, Classic, Feed, Grid, Journal, Magazine, Minimal, Modern, Neutral, Newsletter, Notebook, Reader, Showcase, Stream, Studio, Timeline and Verdict. A few of the most used:

Presets

Inkwell ships 16 colour Presets, and any Preset pairs with any Layout. A dark colour scheme can follow each reader’s device or be forced on from Settings.

Custom themes

Beyond the Layouts and Presets, you can override any CSS variable live from the admin panel; overrides are stored per tenant in the CustomThemeSettings table. There is no drop-in theme folder: a new Layout is a change to the Razor views in the source, so it lives in your fork. See the GitHub repository.

Deployment: Linux / systemd

$ dotnet publish Blog.Web/Blog.Web.csproj -c Release -o /opt/inkwell
$ sudo nano /etc/systemd/system/inkwell.service

[Unit]
Description=Inkwell Blog

[Service]
WorkingDirectory=/opt/inkwell
ExecStart=/usr/bin/dotnet /opt/inkwell/Blog.Web.dll
Restart=always
RestartSec=10
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production

[Install]
WantedBy=multi-user.target

$ sudo systemctl enable --now inkwell

Deployment: Docker

A Dockerfile is included in the repository root. Build and run against your own SQL Server. The database in the connection string must already exist with DBScripts/init.sql applied (sqlcmd -d blog -f 65001 -i DBScripts/init.sql):

$ docker build -t inkwell .
$ docker run -d -p 8080:8080 \
    -e ConnectionStrings__DefaultConnection="Server=host;Database=blog;User Id=sa;Password=...;TrustServerCertificate=True;" \
    -v inkwell-keys:/data/keys -e DataProtection__KeysPath=/data/keys \
    -v inkwell-uploads:/app/wwwroot/uploads \
    --name inkwell inkwell

The two volumes matter: /data/keys holds the encryption keys that protect comment tokens and preview links, and /app/wwwroot/uploads holds everything readers and editors upload. Without them, both are lost the next time the container is recreated.

For a complete stack — the app, SQL Server, and automatic HTTPS via Caddy — use docker-compose.yml, also at the repository root:

$ cp .env.example .env    # set DOMAIN and MSSQL_SA_PASSWORD
$ docker compose up -d

On first boot a one-off db-init container creates the blog database and applies DBScripts/init.sql; re-running it on an existing database changes nothing. The app starts once that succeeds, and once it reports healthy, visiting your domain runs the setup wizard. The app’s own port is never published to the host in this configuration — only Caddy’s 80 and 443 are reachable from outside — so nothing but your own reverse proxy can reach it directly. That is also why the stack can safely set ReverseProxy__TrustForwardedHeaders=true.

Every configuration key uses the standard ASP.NET Core environment-variable convention: a double underscore stands in for the colon in appsettings.json, so ConnectionStrings:DefaultConnection becomes ConnectionStrings__DefaultConnection. No appsettings.json is baked into the image.

Deployment: IIS

1. Install the .NET 10 Hosting Bundle on the server.
2. Publish: dotnet publish Blog.Web/Blog.Web.csproj -c Release -o C:\inetpub\inkwell
3. Create a new IIS site pointing to C:\inetpub\inkwell.
4. Set the application pool to No Managed Code.
5. Ensure the app pool identity has read/write access to the publish directory.

Reverse proxy (nginx)

server {
    listen 443 ssl;
    server_name essays.example.com;

    location / {
        proxy_pass         http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header   Upgrade $http_upgrade;
        proxy_set_header   Connection keep-alive;
        proxy_set_header   Host $host;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header   X-Forwarded-Proto $scheme;
        proxy_cache_bypass $http_upgrade;
    }
}

REST API

/api/v1 serves scripts and headless front ends. Anyone can read published posts (GET /posts, /posts/{slug}), pages (/pages/{slug}), categories and tags, in the shape a reader sees on the page: never review notes, schedules or internal fields.

To write, sign in with POST /api/v1/auth/login (email, password and, with two-factor on, code) for a 15-minute bearer token. Then create, update, publish and delete posts (HTML as content or Markdown as markdown, plus customFields), moderate comments and edit your profile.

• Tokens carry your Desk permissions. A Contributor drafts and edits only their own posts, and publishing needs the publish permission.
• The same checks as the Desk. Publishing runs the structured-data check, saves are kept in revision history, and every write is in the audit trail.
• Accounts are checked on every request, so disabling an account stops its token at once. Errors come back as JSON.
• Off until configured. The API stays off until Jwt:Key is set to a real secret (see Configuration).

Security

• No external trackers. Page analytics are stored locally and counted by a self-hosted script without cookies. The optional geo-IP lookup calls ip-api.com and is cached; to verify crawlers, the server fetches the public IP lists that Google, Bing, Apple, OpenAI and Perplexity publish.
• IP anonymisation. Page-view addresses are stored only as an HMAC-SHA256 under a secret generated for each installation, so a copy of the database does not reveal reader addresses.
• Sign-in. Passwords are hashed with PBKDF2-SHA256 (100,000 iterations, constant-time comparison), cookies are HttpOnly and SameSite=Lax, every form carries an anti-forgery token, and two-factor sign-in is available to every user.
• Automatic IP blocking. Exploit scanners and brute-force sign-ins block themselves (Admin → Security). Proxy headers are ignored unless you declare a trusted proxy, so a client cannot forge its address.
• Immutable audit trail. There is no delete or truncate endpoint for the audit log.
• Upload safety. MIME types are validated, and files are organised under wwwroot/uploads/year/month/.

Development

$ dotnet watch run --project Blog.Web   # hot reload
$ dotnet test                            # xUnit; integration tests skip without SQL Server
$ dotnet run --project tools/FeatureImageGenerator   # OG / feature images

The public stylesheet is precompiled and committed, so dotnet build needs no Node. Node is only needed to regenerate it after adding Tailwind utility classes (build with -p:BuildTailwindCss=true).