📀Installations
Install and configure all the required dependencies for your local environment
Last updated
Install and configure all the required dependencies for your local environment
Last updated
As you can see in the architecture diagram, Harmony has a few dependencies that need to be installed and configured before running. These are the followings:
.NET 8
SQL Server (optional)
PostgreSQL (optional)
MongoDB
RabbitMQ
Redis (optional, only install it on a production environment if you have more than 1 Harmony.SignalR instances)
In case you don't have any experience with installing/running and configuring this kind of software, the following sections will guide you through installing and configuring all these dependencies on your local machine.
If you are going to use Visual Studio for development then the only thing you need to do is to install Visual Studio 2022. Only the ASP.NET and web development workload is needed.
In case you don't want to use Visual Studio for development, you can manual install .NET 8.0 SDK as shown on the following video.
Install either the Developer or Express edition of SQL Server 2022 from the official page. When following the instructions of the video tutorial, take a good look at the connection string property because you are going to use it in your application settings! You are also advised to install SSMS as well in order to test your connection string and be able to access harmony's databases.
In case you want to use PostgreSQL instead of SQL Server, skip this installation and proceed with the PostgreSQL installation.
First of all ensure that you have the correct connection string. Here are few examples that explain how a connection string looks like:
The above connection string is probably the most used one for local development. Server=.; will connect to the default SQL Server instance that is installed on your machine and Integrated Security=True;TrustServerCertificate=True means Windows authentication will be used.
This is different though in case you have a named instance, e.g. SQLEXPRESS (used in the video). In this case use Server=.\<instance name>; rather than Server=.; where SQLEXPRESS is the name of your instance (yours might be different). Example:
Instead of the dot (".") you can use localhost or your PC name as well. For example:
The previous connection strings, use Integrated Security=True so the current Windows account credentials are used for authentication (Windows authentication). You can also use SQL Server Authentication by passing a User Id & Password instead like the following example:
This login must exist on your SQL Server & have access to harmony databases.
The previous example, uses an SQL Server login harmony_user & password %MySuperPass12345instead of Integrated Security=True.
In case you need to know more about SQL Server connection strings, check this page.
In all the SQL Server connection strings that you are going to configure, only change the Server part and optionally replace the Integrated security with User Id & Password as described above. The Database part must not change!
Now that you have your SQL Server connection strings, configure the following 3 properties in the corresponding appsettings.json files:
Harmony.Api: The appsettings.json file contains a ConnectionStrings:HarmonyConnection property that holds the connection string your SQL Server harmony database.
Harmony.Automations: The appsettings.json file contains a ConnectionStrings:HarmonyJobsConnection property that holds the connection string your SQL Server Harmony.Automations.Jobs database.
Harmony.Notifications: The appsettings.json file contains a ConnectionStrings:HarmonyJobsConnection property that holds the connection string your SQL Server Harmony.Notifications.Jobs database.
Installing PostgreSQL is straight forward. Follow the instructions on the following YouTube video to install it on Windows. Follow a respective guide for Linux installation. After installing, configure the required connection strings / migrations as described on the PostgreSQL guide.
MongoDB is very easy to install. Just navigate to the official page, download the installer and run it.
The default port the MongoDB server listens to is the 27017 and it's already configured for you in the Harmony.Automations & Harmony.Integrations.SourceControl appsettings.json files.
Unless you have configured your MongoDB server to run on a different port, you don't have to do anything else.
You can use MongoDB Compass to ensure you have installed MongoDB properly.
RabbitMQ is on of the most important components in Harmony's architecture as it's responsible for asynchronously exchanging messages between applications. There are two steps for installing RabbitMQ, first install the Erlang dependency & then the actual RabbitMQ. Follow the instructions of the YouTube video to install RabbitMQ on your machine.
Notice that in the video also the management plugin is installed, which let's you see all the exchanges, queues & messages on your RabbitMQ server. It is recommended to enabled it as well.
By default RabbitMQ listens to 5672 port which is already been configured for you in all required apps, so unless you have configured the server to listen on a different port, once again you don't have to change anything. The configuration is defined in the following services in their corresponding appsetting.json files:
Harmony.Api
Harmony.Automations
Harmony.Notifications
Harmony.SignalR
Harmony.Integrations.SourceControl
On production environments, you usually create logins with custom username & password but for your local installation you can leave it as it is.
Redis installation is completely optional and required only in production environment and only when you have more than one Harmony.SignalR instances.
In you want to install and configure it on your local machine, the easiest way is to do it is via a GitHub package which you can find here.
Redis is being used on on Harmony.SignalR project so there's only one place to configure it in case you want to use it. Check the RedisConnectionString property, inside its appsettings.json file.
By default it's an empty string, which means Redis will not be used. In case you install Redis, by default it runs on port 6379 so the connection for your local environment would look like this:
In the future, all connection strings might be included inside the "ConnectionStrings" property so always keep an eye on the Changelogwhen new builds are released.
Lots of efforts have been made so far and will continue to do so, to keep docs up to date, either for describing the tool's features (e.g. gifs, YouTube videos) or explaining the architecture & how to guides.
You are responsible to install & configure Harmony regardless the environment.
Harmony is an amazing project in many aspects and will keep growing at a fast pace. It's not a simple web app that you can click F5 and run it. It requires some basic understanding of installing software like all these you read on this page and configuring their connection strings.
Production, Docker & Kubernetes is a different story. It requires that you understand their concepts and you have experience of deploying solutions based on a microservice architecture.
You have a lot to learn from a project like this, either by studding the codebase as a software engineer/architect or using it as a project management tool for your projects. Enjoy!
