Except running from the releases package, you can also run
OpenCatapult by building from the source code.
There are cases that make people want to do it. For example, they want to run
OpenCatapult in a platform that the release package has not been provided. Or they want to contribute in a bug fix so they need to debug it locally. Or maybe they want to try some new features that have not been released yet.
One thing to note for sure is that this procedure might sounds too technical for average users. This is because it is actually intended to be used by someone who are familiar with basic programming knowledge. They don't need to be an ASP.NET Core programmer. As long as they are comfortable with entering some commands into a shell (PowerShell), then they are good to go.
This is the only required tool to run build
OpenCatapult. Other tools are optional as they are needed on some conditions only
This is required by the Web UI. You can skip this if you go all CLI.
PowerShell is only required if you want to build the code by using the provided build scripts.
If you are on Windows, the PowerShell 5 should have been installed out of the box on your machine
If you are on Linux or Mac, you can get the cross-platform PowerShell 6
This is only used to clone the source code. If you prefer to download the ZIP package instead, you don't need it
A code editor (optional)
OpenCatapult source code is stored in the GitHub repository.
You can obtain the source code either by downloading the ZIP package or cloning it into your local machine.
Cloning the source code is simple. One way to do it is by entering this command to your favorite shell:
git clone https://github.com/Polyrific-Inc/OpenCatapult
Then go to the root folder:
From this point you have two options: build the source code using PowerShell scripts, or build manually.
When running the scripts, you might get execution policy error. In most of the time it can be fixed by setting the execution policy to
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
Please check the following article for more details about execution policies.
You will need to build the API, Engine, and UI (either CLI or Web) to run
OpenCatapult. In production scenario, the components are typically installed in separated machines. However, in the development scenario, we will run them all in your local machine. We have prepared a script to help you run the components easier. Run this command in PowerShell:
Note that running this script will run all 4 of the components. If you want to skip CLI or Web, you can add the
-noWeboption. For example if you want to go all CLI, use the following command instead:
The script will ask you to input the database provider and connection string. To minimize the hazzle of starting
OpenCatapult for the first time, you can just use the default database provider, which is SQLite. It doesn't require you to provide a running SQL Server instance. However, if you prefer to use SQL Server, please enter "
mssql" as the database provider, and enter a valid connection string, e.g.
Please enter the overriden value without quotation marks.
Please don't close the first powershell window since it is being used to run the API, which is being used by Engine, CLI, and Web. To learn more about how opencatapult components relate to each other, please check the following article.
If you want to build the API, Engine, CLI, or Web component individually, for example if you want to install them in separate machines, you can run the script for each of the component separately. Please find more details about them in the Build Scripts section.
If for any reasons you cannot run the PowerShell scripts, you can always build the source code manually. Please go to the Manually Build The Components section, and go back here when finished.
Note: The following tutorial uses the opencatapult CLI. If you want to create the project by using Web UI, please follow this link
OpenCatapult allows you to define task providers for all types of applications and devOps resources. We have pre-loaded OpenCatapult with an example code generator provider based on a .NET Core MVC template which will deploy directly to your local machine at this location:
To get started, open up a PowerShell window that will be used as your CLI shell and enter the following from within your OpenCatapult folder:
When you previously applied migrations to initiate the database, a default user was created. You can use this user to login. When you're prompted to enter the password, the default password is "
dotnet occli.dll login --user email@example.com
We strongly advise you to change the default password (or just remove the default user), especially when you deploy the API into public environment:
dotnet occli.dll account password update
We need to register Engine so it can communicate with the API without problem. It involves step to register the Engine via CLI, and enter the generated token back in the Engine itself. If you have multiple Engine instances, you need to do this procedure on each of them.
Activate the CLI shell, and enter this command:
dotnet occli.dll engine register --name Engine001
After the Engine is registered, let's generate a token for it, and copy the generated token:
dotnet occli.dll engine token --name Engine001
Activate the Engine shell, go to the engine's published folder, and set the
AuthorizationToken config with the copied generated token:
cd .\publish\engine\dotnet ocengine.dll config set --name AuthorizationToken --value [the-generated-token]
Let's start the Engine:
dotnet ocengine.dll start
You can find more details about these procedure at Manage engine registration
And now, you're good to go to create a project. We will use
sample template, which will give you some pre-defined models, and a job definition with a single
Generate task. The task uses a built-in generator provider called
Polyrific.Catapult.TaskProviders.AspNetCoreMvc, which will generate a starter ASP.NET Core MVC application.
Activate the CLI shell, and enter this command:
dotnet occli.dll project create --name first-project --client Polyrific --template sample
During the process you will be prompted to enter
Admin Email. Please fill it with your email.
After the project is created you can check the created elements in it. For example you might want to check the created data models:
dotnet occli.dll model list -p first-project
As explained in introduction, the automation logics happens in the engine. We define what the engine shall do in what we call job. A job can contain many tasks as needed by our development, build, and deployment pipeline. When we want to ask the engine to run a job, we add it into the queue, and any active engine will pick it up and execute it.
The project that you've just created contains a
Default job definition with a
Generate task in it.
dotnet occli.dll job get -n Default -p first-project
Let's add the job to the queue so Engine can pick and execute it.
dotnet occli.dll queue add -j Default -p first-project
The above command will print the created queue in the CLI. You should check out the
Id since this will be used to get the log or queue status. If this is your first time adding queue, the
Id should be 1.
You can monitor the live progress by using the
queue log command and passing the queue
dotnet occli.dll queue log -n 1 -p first-project
The final status of the process can be checked by this command:
dotnet occli.dll queue get -n 1 -p first-project
It will tell you the status of each task execution, whether it's Success or Failed, along with the error remarks if any.
After creating your first project, you can: