Oqtane Silent Installation Guide

Actually, I’m not really “writing” — I’m using the Windows dictation feature (Windows key + H). So right now, I’m just having coffee and talking to my computer. I’m still in El Salvador with my family, and it’s like 5:00 AM here. My mom probably thinks I’ve gone crazy because I’ve been talking to my computer a lot lately. Even when I’m coding, I use dictation instead of typing, because sometimes it’s just easier to express yourself when you talk. When you type, you tend to shorten things, but when you talk, you can go on forever, right?

Anyway, this article is about Oqtane, specifically something that’s been super useful for me — how to set up a silent installation. Usually, when you download the Oqtane source or use the templates to create a new project or solution, and then run the server project, you’ll see the setup wizard first. That’s where you configure the database, email, host password, default theme, and all that.

Since I’ve been doing tons of prototypes, I’ve seen that setup screen thousands of times per day. So I downloaded the Oqtane source and started digging through it — using Copilot to generate guides whenever I got stuck. Honestly, the best way to learn is always by looking at the source code. I learned that the hard way years ago with XAF from DevExpress — there was no documentation back then, so I had to figure everything out manually and even assemble the projects myself because they weren’t in one solution. With Oqtane, it’s way simpler: everything’s in one place, just a few main projects.

Now, when I run into a problem, I just open the source code and tell Copilot, “OK, this is what I want to do. Help me figure it out.” Sometimes it goes completely wrong (as all AI tools do), but sometimes it nails it and produces a really good guide.

So the guide below was generated with Copilot, and it’s been super useful. I’ve been using it a lot lately, and I think it’ll save you a ton of time if you’re doing automated deployment with Oqtane.

I don’t want to take more of your time, so here it goes — I hope it helps you as much as it helped me.

Oqtane Installation Configuration Guide

This guide explains the configuration options available in the appsettings.json file under the Installation section for automated installation and default site settings.

Overview

The Installation section in appsettings.json controls the automated installation process and default settings for new sites in Oqtane. These settings are particularly useful for:

• Automated installations – Deploy Oqtane without manual configuration
• Development environments – Quickly spin up new instances
• Multi-tenant deployments – Standardize new site creation
• CI/CD pipelines – Automate deployment processes

Configuration Structure

{
  "Installation": {
    "DefaultAlias": "",
    "HostPassword": "",
    "HostEmail": "",
    "SiteTemplate": "",
    "DefaultTheme": "",
    "DefaultContainer": ""
  }
}
  

SiteTemplate

A Site Template defines the initial structure and content of a new site, including pages, modules, folders, and navigation.

"SiteTemplate": "Oqtane.Infrastructure.SiteTemplates.DefaultSiteTemplate, Oqtane.Server"

Default options:

• DefaultSiteTemplate – Home, Privacy, example content
• EmptySiteTemplate – Minimal, clean slate
• AdminSiteTemplate – Internal use

If empty, Oqtane uses the default template automatically.

DefaultTheme

A Theme controls the visual appearance and layout of your site (page structure, navigation, header/footer, and styling).

"DefaultTheme": "Oqtane.Themes.OqtaneTheme.Default, Oqtane.Client"

Built-in themes:

• Oqtane Theme (default) – clean and responsive
• Blazor Theme – Blazor-branded styling
• Bootswatch variants – Cerulean, Cosmo, Darkly, Flatly, Lux, etc.
• Corporate Theme – business layout

If left blank, it defaults to the Oqtane Theme.

DefaultContainer

A Container is the wrapper around each module, controlling how titles, buttons, and borders look.

"DefaultContainer": "Oqtane.Themes.OqtaneTheme.Container, Oqtane.Client"

Common containers:

• OqtaneTheme.Container – standard and responsive
• AdminContainer – management modules
• Theme-specific containers – match the chosen theme

Defaults automatically if left empty.

Example Configurations

Minimal Configuration

{
  "Installation": {
    "DefaultAlias": "localhost",
    "HostPassword": "YourSecurePassword123!",
    "HostEmail": "admin@example.com"
  }
}
  

Custom Theme and Container

{
  "Installation": {
    "DefaultAlias": "localhost",
    "HostPassword": "YourSecurePassword123!",
    "HostEmail": "admin@example.com",
    "SiteTemplate": "Oqtane.Infrastructure.SiteTemplates.DefaultSiteTemplate, Oqtane.Server",
    "DefaultTheme": "Oqtane.Theme.Bootswatch.Flatly.Default, Oqtane.Theme.Bootswatch.Oqtane",
    "DefaultContainer": "Oqtane.Theme.Bootswatch.Flatly.Container, Oqtane.Theme.Bootswatch.Oqtane"
  }
}
  

Troubleshooting

• Settings ignored during installation: Ensure all required fields are filled (DefaultAlias, HostPassword, HostEmail).
• Theme not found: Check assembly reference and type name.
• Container displays incorrectly: Use a container matching your theme.
• Site template creates no pages: Ensure your template returns valid page definitions.

Logs can be found in Logs/oqtane-log-YYYYMMDD.txt.

Best Practices

• Match your theme and container.
• Leave defaults empty unless customization is needed.
• Test in development first.
• Document any custom templates or themes.
• Use environment-specific appsettings (e.g. appsettings.Development.json).

Summary

The Installation configuration in appsettings.json lets you fully automate your Oqtane setup.

• SiteTemplate: defines structure
• DefaultTheme: defines appearance
• DefaultContainer: defines module layout

Empty values use defaults, and you can override them for automation, branding, or custom scenarios.