In this article, I’ll show you what to do after you’ve obtained and opened an Oqtane solution. Specifically, we’ll go through two different ways to set up your database for the first time.
Using the setup wizard — this option appears automatically the first time you run the application.
Configuring it manually — by directly editing the appsettings.json file to skip the wizard.
Both methods achieve the same result. The only difference is that, if you configure the database manually, you won’t see the setup wizard during startup.
Step 1: Running the Application for the First Time
Once your solution is open in Visual Studio, set the Server project as the startup project. Then run it just as you would with any ASP.NET Core application.
You’ll notice several run options — I recommend using the HTTPS version instead of IIS Express (I stopped using IIS Express because it doesn’t work well on ARM-based computers).
When you run the application for the first time and your settings file is still empty, you’ll see the Database Setup Wizard. As shown in the image, the wizard allows you to select a database provider and configure it through a form.
There’s also an option to paste your connection string directly. Make sure it’s a valid Entity Framework Core connection string.
After that, fill in the admin user’s details — username, email, and password — and you’re done. Once this process completes, you’ll have a working Oqtane installation.
Step 2: Setting Up the Database Manually
If you prefer to skip the wizard, you can configure the database manually. To do this, open the appsettings.json file and add the following parameters:
The database provider type (e.g., SQLite, SQL Server, PostgreSQL, etc.)
The connection string
The admin email and password for the first user — known as the host user (essentially the root or super admin).
This is the method I usually use now since I’ve set up Oqtane so many times recently that I’ve grown tired of the wizard. However, if you’re new to Oqtane, the wizard is a great way to get started.
Wrapping Up
That’s it for this setup guide! By now, you should have a running Oqtane installation configured either through the setup wizard or manually via the configuration file. Both methods give you a solid foundation to start exploring what Oqtane can do.
In the next article, we’ll dive into the Oqtane backend, exploring how the framework handles modules, data, and the underlying architecture that makes it flexible and powerful. Stay tuned — things are about to get interesting!
I’m returning to work with Oqtane, and to be honest, we’re exploring new frameworks at the office that will help us expand our market reach. We specialize in a specific type of development and don’t want to move too far away from .NET in general. We’ve used Oqtane in the past—I’ve even installed it on Linux—but I want to conduct fresh research: try it again, get a feel for it, and potentially move some production-sized projects to it.
There’s a lot to understand about Oqtane, especially because it’s a truly layered development framework where you need to work across different layers. This will be the first article in a series that serves both as a guide and as personal mental notes of things I don’t want to forget the next time I develop prototypes or production sites with Oqtane.
The first topic we’ll review is how to install Oqtane and start it up. Here are the steps I usually follow.
Choosing Your Development Approach
The first question you should ask yourself is: How do you want to develop? There are a few ways to do it, and I’ve watched every video about Oqtane over the last two weeks. Here are your three main options:
Option 1: Clone or Download from GitHub (Main Branch)
The old way was to simply go to GitHub and clone or download the source from the main branch, which is actually the development branch. This approach allows you to see all the ins and outs of the framework—how each module is created and registered, how they use repositories, and so on.
However, this may be overwhelming at the beginning. To be honest, since Oqtane has several layers, I got confused many times and wrote code in the wrong layer more than once.
Option 2: Download a Specific Version from Releases
You can also download just the version you want from the releases section on GitHub. This gives you a stable, versioned codebase to work with.
Option 3: Use .NET Templates (Recommended for Beginners)
Now they have .NET new templates available. If you’re a beginner, I strongly suggest installing the .NET templates and using dotnet new because the structure is much more simplified.
However, if you want to understand the ins and outs of the application framework and how it works, I strongly recommend taking a look at the source code.
Installation Resources
Source Code Repository
You can get the source code at this GitHub repository:
https://github.com/oqtane/oqtane.framework
In the README of that repository, you’ll find instructions for installing the templates.
Using the Templates
Here’s an example of how to install and use the templates:
dotnet new install Oqtane.Application.Template
dotnet new oqtane-app -o MyCompany.MyProject
cd MyCompany.MyProject
dotnet build
cd Server
dotnet run
Release Versions
In the releases section, you can find the source code for each specific version:
Solution structure when using the downloaded source:
OqtaneFramework/
├── .github/ # GitHub configuration and issue templates
├── Oqtane.Application/ # .NET Template for creating new Oqtane apps
├── Oqtane.Client/ # Core Blazor WebAssembly client framework
├── Oqtane.Server/ # Core ASP.NET server framework
├── Oqtane.Shared/ # Shared contracts, models, and interfaces
├── Oqtane.Maui/ # MAUI mobile application support
├── Oqtane.Package/ # NuGet packaging and distribution tools
├── Oqtane.Updater/ # Framework update/upgrade utilities
├── screenshots/ # Marketing and documentation images
├── Oqtane.sln # Main solution file
├── Oqtane.Maui.sln # MAUI solution file
├── Oqtane.Updater.sln # Updater solution file
└── Configuration Files # Build, deployment, and Git configs
In the source you will also find the source of around 27+ admin modules, which is a great way to learn how to create your own modules.
Dashboard
Files (file management)
Jobs (background job scheduler)
Languages (localization)
Login/Register/Reset (authentication)
Logs (system logging viewer)
ModuleDefinitions (module registry)
Modules (module instance management)
Pages (page/route management)
Profiles (user profiles)
RecycleBin (soft delete management)
Roles (role-based access)
Search/SearchResults
Settings (system configuration)
Site/Sites (multi-tenancy)
SQL (database query tool)
SystemInfo (diagnostics)
Themes (theme management)
Upgrade (version upgrades)
UrlMappings (URL rewriting)
Users (user management)
Visitors (analytics)
Wrapping Up
That’s it for this first article! We’ve covered the basics of getting Oqtane installed and understanding the different approaches you can take depending on your experience level and project needs.
In the next article, we’ll dive into starting up the application and picking a database provider. This is where things get interesting, as Oqtane supports multiple database options, and understanding how to configure them properly is crucial for getting your project off the ground.
Stay tuned, and happy coding!
This is part 1 of a series documenting my journey with Oqtane. Check back soon for the next installment.
It’s Sunday — so maybe it’s time to write an article to break the flow I’ve been in lately. I’ve been deep into researching design patterns for Oqtane, the web application framework created by Shaun Walker.
Today I woke up really early, around 4:30 a.m. I went downstairs, made coffee, and decided to play around with some applications I had on my list. One of them was HotKey Typer by James Montemagno.
I ran it for the first time and instantly loved it. It’s super simple and useful — but I had a problem. I started using glasses a few years ago, and I generally have trouble with small UI elements on the computer. I usually work at 150% scaling. Unfortunately, James’s app has a fixed window size, so everything looked cut off.
Since I’ve been coding a lot lately, I figured it would be an easy fix. I tweaked it — and it worked! Everything looked better, but a bit too large, so I adjusted it again… and again… and again. Before I knew it, I had turned it into a totally different application.
I was vibe coding for four or five hours straight. In the end, I added a lot of new functionality because I genuinely loved the app and the idea behind it. I added sets (or collections) — basically groups of snippets you can assign to keys 1–9. Then I added autosave, a settings screen, and a reset option for the collections. Every time I finished one feature, I said, “Just one more thing.” Five minutes turned into five hours.
When I was done, I recorded a demo video. It was a lot of fun — and the result was genuinely useful. I even want to create an installer for myself so I can easily reinstall it if I ever reformat my computer. (I used to be that guy who formatted his PC every month. Not anymore… but you never know.)
Lessons From Vibe Coding
I learned a lot from this little experiment. I’ve been vibe coding nonstop for about three months now — I’ve even used up all my Copilot credits before the 25th of the month more than once! Vibe coding is a lot of fun, but it can easily spiral out of control and take you in the wrong direction.
Next week, I want to change my approach a bit — maybe follow a more structured pattern.
Another thing this reminded me of is how important it is to work in a team. My business partner, José Javier Columbie, has always helped me with that. We’ve been working together for about 10 years now. I’m the kind of developer who keeps rewriting, refactoring, optimizing, making things faster, reusable, turning them into plugins or frameworks — and sometimes the original task was actually quite small.
That’s where Javier comes in. He’s the one who says, “José, it’s done. This is what they asked for, and this is what we’re delivering.” He keeps me grounded. Every developer needs that — or at least needs to learn how to set that boundary for themselves.
Final Thoughts
So that’s my takeaway from today’s vibe coding session: have fun, but know when to stop.
I’ll include below the links to:
James Montemagno’s original HotKey Typer repository
