Install OpenRose on Standalone Computer
- OpenRose WebUI front-end
- OpenRose API back-end
- SQL Server Database
Direct Link to YouTube Video : https://www.youtube.com/watch?v=yuGIZtxsXIA
Video Transcript :
Hi, today we are going to talk about the `Standalone Installation of OpenRose`. By "Standalone", I mean it will be installed on a single Windows computer and will be accessible locally on that specific machine.
To run any .NET application, you will need to install the .NET runtime. OpenRose currently runs on .NET Version 9.x, so you will need the .NET runtime version 9.x. Here is the download link: Download .NET 9.0. For a standalone installation, you will require the x64 runtime environment for .NET Core. This will install the .NET runtime as well as any other necessary components required to run .NET Core in standalone mode. If you are going to install it on IIS, then you would need the hosting bundle, which we will discuss later.
OpenRose packages are available as releases and are essentially a web deployment or a zip file containing the compiled versions of the web UI application and the API application. Both are required to start the application and connect it to the database. You can find more information about a standalone installation on the Wiki page here. Simply go to the Wiki and look for the helper batch file for standalone installation.
We have packaged something called the `Start_OpenRose.bat` file, which is included in one of the packages. It contains step-by-step instructions on how to start your application as a standalone application on a computer.
Now, before we proceed further, let me show you an overview of the architecture for a standalone computer. If we have a Windows computer and we are going to talk about the Windows installation as a standalone installation, we should first have an SQL Server database. It should either be installed locally or you should have the ability to connect to the SQL Server over the network. Today, we are purely talking about having everything installed on a single computer, making it available as a personal Requirements Management Tool for individual users.
SQL Server is necessary as a database. If you don't have SQL Server available on your computer, you can search for and install SQL Server Express Edition. This is a free version available from Microsoft, and you can find the direct download link here. Simply download the SQL Server Express Edition, and once it is downloaded, the person who installs the SQL Server on that computer becomes the administrator. The installation is straightforward! Just download the MSI or the installer file and then run it. The installer will guide you through the process of installing it on your individual computer.
Once the SQL Server is installed, you can see who the local admin is on your SQL Server. Simply open the command prompt on your computer. In my case, when I open the command prompt, it shows that I am logged in as Martin. If I also use the command "whoami", I should be able to see my exact network or computer name, which includes the computer name plus my username. This is how we identify who becomes the administrator on your SQL Server. In my case, because I am logged in as Martin on this computer, I will use that account to connect to SQL Server as the SQL Server administrator.
Jumping back to this diagram: after getting SQL Server up and running, we don't need to create any databases there. OpenRose will do it for us automatically. We just need to provide the connection to SQL Server. The next step is to ensure we have access to the connection string. When you install SQL Server, you also get the application called Microsoft SQL Server Management Studio (SSMS). If this is not installed automatically, you can download the latest version of SSMS from this URL. Once downloaded, install it using the same account used for installing SQL Server.
Once Microsoft SQL Server Management Studio is installed, you can connect to your local SQL Server. For instance, my computer name is BAGHEERA, so my local SQL Express instance is `BAGHEERA\SQLExpress`. Let me disconnect from this one and reconnect to the database engine. I'm just passing in `BAGHEERA\SQLExpress` and using Windows Authentication, which picks up `BAGHEERA\Martin` as my username. Click on "Trust server certificate" and connect. By default, you won't see the OpenRose database because it is not yet configured and we've not yet started the application. However, once you start the application and it successfully runs, then it will create the database for you and set up the necessary tables and objects.
If you want to back up your database, right-click and go to "Tasks" > "Backup". There are plenty of guidelines available online on how to do SQL Server backups and restorations, so you can keep taking backups of your database as needed from your local environment.
Now, the next step is to unzip the downloaded files. In my case, I'm going to unzip them into the OpenRose folders I created at `C:\OpenRose`. The two files I downloaded from the GitHub release page for OpenRose are here. Let me simply extract all the data for the API version. It should create an `OpenRose.API` folder and contain all the necessary files. Now, do the same for the web UI.
In the web UI, my application settings indicate that the application starts on port number 7673 and connects to the OpenRose API on port number 6736. This setup is depicted in the architecture diagram, where the web UI runs on 7673 and the API runs on 6736 by default. You can modify these port numbers in the app settings of the individual folders where you extracted the zip files.
In the API app settings, we not only specify the port number but also connect to a SQL Server database. You need to provide the connection string, which can be obtained from SQL Server itself. For instance, my SQL Server instance is named `BAGHEERA\SQLExpress`, and the connection string should replace `localhost` with `BAGHEERA\SQLExpress`.
Instead of updating the `appsettings.json` file in the API folder, you can use environment variables. Go to system properties and find environment variables. Create a new system environment variable with the connection string. Ensure the correct server name and instance are provided.
Once this setup is done, you will be able to start the application and connect to the database without needing to maintain the app settings file locally.
So, I just need to take this `BAGHEERA\SQLExpress` and that's what we need to replace up here. Let the database name be the same and let the trusted connection be true. The only thing I need to replace is my local machine names. Instead of `local DB`, it's going to be `BAGHEERA` in this case because my computer name is `BAGHEERA`. Then, here I'm just going to use `SQLExpress`. Now we can update this `appsettings.json` file in the API project or in the API folder, or you can leave this as it is. You don't need to update this because next time when the new version is available, you just do the extraction. You simply copy the extracted file over to your location, which means this data will be overridden. So, we just don't want to keep maintaining this file locally. That's why we are going to use something called an environment variable.
In your system, you should be able to get to environment variables. So, I'm just going to open my environment variable settings. This is available as system properties. You simply go look for environment variables in the settings and it will allow you to open up this dialog box to modify environment variables. What I'm going to do is show you that we can use a system environment variable. You can click on "New" and create a new system environment variable. It's going to have this `ConnectionStrings__ItemzContext`, which is the name of the database connection string. The same information is available in our `appsettings.json` file. Let me just reopen this file. You can see, oh sorry, this is the web API version, it's not the one I'm looking for. The API version `appsettings.json` file is the file in which we have the connection string, and the name of the connection string is `ItemzContext`. This is exactly what we have depicted here: `ConnectionStrings__ItemzContext`. Then I'm passing the server name to be `BAGHEERA` with a single slash—it's not a double slash here, it's a single slash. In the JSON file, it will be a double slash because we need to escape the slash with another slash to be added since it's a JSON format. But here you just need to provide a single slash and then the database name that you would like to connect to. We have these trusted server certificates set to `true`.
So, if you just simply copy this over in the environment variable here and replace the server name according to what you found in your SQL Server, you will see that `BAGHEERA\SQLExpress` is my server name. `SQL Express` is my server name here, and that's what I'm using to connect to the database. Because I have the environment variable, it overwrites the value we have in the app settings. This means this value here will be overridden with the one that is coming from the environment variable, so I don't need to keep maintaining this file. Let's close this and go back to these two folders where we have done the extraction of these zip files. Now, the zip files are not required, so I can just simply go ahead and delete them or just leave them around depending on your preference.
In the web UI, we have placed a file called `Start_OpenRose.bat`. Now, this file is doing nothing special; it just says to go one level up to a folder that starts with `OpenRose.API`. You may have `OpenRose.API` version one, version two, version three, etc. It doesn't matter. Whatever the version name is, the folder should start with the name `OpenRose.API`. It goes inside that folder and simply starts the application. So it just starts the `OpenRose.API.exe` and `OpenRose.WebUI.exe`. The same thing goes for the web UI. There’s an exe file you can run manually, or you could just double-click on this batch file and it'll simply start both the `OpenRose.API.exe` and `OpenRose.WebUI.exe`. The API is in the API folder, and the web UI is in the web UI folder.
Let's do that. Now that we have the environment variable and the SQL Server configured, in my SQL Server, I may already have some data because I was using this for trying out different installation procedures and running some necessary scripts to generate some sample data. So there might be some sample data already available in my instance. When you do this on your computer, you will have no Projects, no Requirements, no Item Types. You will start fresh if you do it for the first time.
Now, let me double-click on this file. Here, I'm getting a "Windows protected your PC" warning from Microsoft Defender, so I just need to say "Run anyway." We have not signed our batch file; that's why this error is popping up. In the future, we may sign the batch file so that this error will go away. Once the application starts, you will see two command windows running: this is the API command window, and this is the WebUI command window. These will keep rolling and showing you the log files as and when you access the application.
Now that the application is running, we should be able to connect to port 7673 on localhost. Let me open a browser window, and say https://localhost:7673 to connect to my OpenRose on the local computer, completely isolated from the network. It's for my private use for managing my requirements in a private database on my computer. It's just like a Word document or an Excel file that I open on my computer, but it has a lot of advantages because you have the complete flexibility to use different features like traceability, change log, baselining, snapshots, orphan items—all those capabilities are available on your local computer.
Here in the projects, I already have these projects as I say these are my sample projects that I have been using for demo purposes and I can still connect to them on my local computer. But this time, I'm running everything from this local environment or the local instance that I started using the batch file. That's how you can work with OpenRose if you download the release package. If you already have SQL Server installed and you are the local admin with access to SQL Server, this is how you could simply use OpenRose to start using it in your local standalone environment.
Let's go back to the diagram. We have SQL Server, we know who we are, who installed SQL Server, and so we know we can connect using our Windows internal credentials to connect to SQL Server. It's like a single sign-on. Once you’ve authenticated yourself, the application using the environment variable to connect to SQL Server will be able to use your login instance and allow you to work with your data on your local computer.
This is how you can configure a standalone environment of OpenRose, including the OpenRose web UI, the OpenRose API, and the SQL Server, all in a single environment. This is how you connect to the web UI interface using http://localhost:7673, which is the default port number. We also discussed how you can change these port numbers in the appsettings.json file within those folders, whether it is the WebUI folder or the API folder.
Thank you, and please share this information with others who may benefit from using OpenRose as a standalone application on a Windows computer. Thank you and bye for now.
DOCUMENTATION REF :
Helper Batch File ‐ Start Standalone OpenRose · OpenRose/OpenRose Wiki · GitHub
Comments
Post a Comment