How to initialize an Oqtane Repo

git submodules can be tricky but rewarding

Init Oqtane with a Submodule

If you want to learn how to use Oqtane, a framework for building Blazor applications, you can find official tutorials online. I have been using Oqtane since it was launched and I think it is a great tool for creating web apps for work and community purposes. In this post, I will share some tips on how to set up your project for collaborative development with Oqtane. I think it is important that anyone who wants to contribute to your codebase can easily get started by cloning the development branch and having everything they need ready. To achieve this, you will need to follow some extra steps that will include the source code of Oqtane in your project and allow you to make changes to your own version of the framework if necessary.

Tracking your own versions of Oqtane in release branches

If you want to learn more about Oqtane and how it works, you can access the source code and explore it yourself. You can also debug the code and see how it behaves in different scenarios. To keep your team updated with the latest version of Oqtane, you can use a local fork and create release branches that follow the gitflow naming convention, such as release/v3.2.1. This way, you can match the release tags in the original Oqtane repository. You can also specify a particular version of Oqtane when you initialize your repository, by using a readme and a .gitmodules file like this:

[submodule "oqtane.framework"]
	path = oqtane.framework
	url = https://github.com/[your-org]/oqtane.framework
	branch = release/v3.2.1
	ignore = dirty

A word of caution: sometimes the branch name is not enough to ensure that the submodule is on the right release branch. You may need to verify manually that the submodule is pointing to the correct commit. I’m not sure why submodules are finicky.

Creating your base module

To run Oqtane.Server for the first time, you need to pull your repo and update the submodule. Then, open the Oqtane.sln file, select Oqtane.Server as the startup project and launch the app. You will see a startup screen where you can use the default settings and create a user called 'host' with a secure password that you can remember for a while. The app will create the database and start the site. Go to the admin panel, module management and create a new module. The new modules will appear in the root folder of your repo next to the framework. Stop the app and close the solution when you are done. I’m not going into great detail here as this is covered in most of the intro videos.

Changing package references to project references

The first step to create the base module is to set up three projects that depend on the Oqtane.Server, Client and Shared libraries. You have to replace the package references with project references in each project. Sometimes Visual Studio might not recognize the changes and you have to reopen the solution to make sure everything is correct before you commit and push your changes.

Ready to Roll

You have completed the necessary steps to start creating your module or modules. This method allows you to have a separate set of repo that you can manage and a full source code for reference as well as a full debugging experience.