Getting Started

Environment

Like any other application, StarterKit has the following environment requirements:

• Microsoft SQL Server
• DotNet 8
• NodeJS 20.x and Yarn

Additionally, we recommend installing the StarterKit Development Rider plugin for more efficient development, as well as for (add something else) improving the workflow.

Source Code

To start using StarterKit, you need to clone its Git repository located here. If you don't have access, please contact StarterKit.Development@itransition.com to request access.

First Run

There are two ways to perform the initial setup of StarterKit: automated and manual. However, we recommend using the automated setup. Nonetheless, we also provide the manual setup for reference.

Automated Setup

You'll need a .dev.env file, which you can obtain from your TeamLead. This file is located under .gitignore and is expected to be unique for each team member.

CMD

stk init

note

If you're the TeamLead initiating the project, below you'll find an example .dev.env file.

Now, onto the most enjoyable part, launching.

To start, you can use the scripts provided with the codebase:

CMD

stk start-servers
stk start-webapp

Important note

After fetching new changes those commands are mandatory to run

CMD

wex lib pack --all
wex mod pack --all --lock-version
wex app node

Or

CMD

wex lib pack --all
wex mod pack --all --lock-version
pnpm install (from StarterKit.App.Main.UI)

In most cases, you'll probably use an IDE to run the application (after all, we're writing this documentation for developers).
To start the Backend, open src/StarterKit/StarterKit.sln using your favorite IDE (we recommend using Rider with the plugin provided with StarterKit) and launch the StarterKit.Identity and StarterKit.App.Api projects.
To run the Web App, open <REPO_ROOT>/src/app-main/StarterKit.App.Main.UI_ and run pnpm start.

Appendix I: .dev.env file

.dev.env

DEV_ID=1
DB_NAME=starter-kit
# SQL_SERVER=localhost
# SQL_USERNAME=sa
# SQL_PASSWORD=...
DEV_EMAIL=who-is-john-galt@itransition.com
SERVICE_BUS_CONNECTION_STRING=Endpoint=sb://....=
TWILIO_ACCOUNT_SID=...
TWILIO_AUTH_TOKEN=...
TWILIO_MESSAGE_SERVICE_SID=...
SENDGRID_KEY=SG...
ZOOM_VIDEO_SDK_KEY=...
ZOOM_VIDEO_SDK_SECRET=...
AZB_ACC=...
AZB_KEY=...
AZB_CONTAINER=...

 

Prop	Required?	Description
DEV_ID	Yes	Developer's unique identifier. We use it to differentiate when sharing common resources, such as ServiceBus namespaces, for example. Typically, we use numerals as values.
DB_NAME	Yes	Database name
SQL_SERVER	No	Microsoft SQL Server domain, defaulting to "localhost". Typically, you will need to override this value if you run SQL Server in Docker containers.
SQL_USERNAME	No	Default: <NULL>
SQL_PASSWORD	No	Default: <NULL>
DEV_EMAIL	Yes	User email for creating an initial admin user. We recommend using real emails, as system notifications will be sent to them.
SERVICE_BUS_CONNECTION_STRING	Yes	Endpoint=sb://....=
TWILIO_ACCOUNT_SID	Yes	The Twilio account will be used for SMS messages during the Multi-Factor Authentication (MFA) process.
TWILIO_AUTH_TOKEN	Yes
TWILIO_MESSAGE_SERVICE_SID	Yes
SENDGRID_KEY	Yes	SendGrid is widely used by the system to send various types of notifications via email. (SG.....)
ZOOM_VIDEO_SDK_KEY	Yes	The Zoom Video SDK is used for in-system video conferencing.
AZB_ACC	Yes	Storage Account name in Azure Blob Storage
AZB_KEY	Yes	Secret access key to Azure Storage Account.
AZB_CONTAINER	Yes	The name of a container inside Azure Blob Storage.

Appendix II: Manual Setup

warning

Typically, you shouldn't use manual setup. I trust you have reasons for doing so.

To start, you'll need to create an appsettings.Personal.json file with personalized settings in the following directories:

• src/StarterKit/StarterKit.App.Api
• src/StarterKit/StarterKit.App.Migrations (only if you want to override the Database Connection String)
• src/StarterKit/StarterKit.Identity
• src/StarterKit/StarterKit.Identity.Migrations (only if you want to override the Database Connection String)

Typically, you should obtain appsettings for StarterKit.App.Api and StarterKit.Identity from your TeamLead.
If you are the TeamLead initiating the project from scratch, use appsettings.schema.json in the respective folders for reference.

When setting the Database Connection String, bear in mind that you may need to use TrustServerCertificate=True.

Database

Next, create a database using your preferred database management tool. Remember that the database name must match the one in the Database Connection String (default name is "starter-kit").

Now, we can apply migrations and create the database schema. Navigate to the root of the Git repository and run the command stk database update in the command line.

CMD

stk database update

StarterKit uses SQL Server for Distributed Cache (Redis or an alternative is recommended for production), so you'll need to install the dotnet sql-cache utility.

CMD

dotnet tool install --global dotnet-sql-cache

Afterward, we can create tables for Microsoft.Extensions.Caching.SqlServer.

CMD

dotnet sql-cache create "<CONNECTION STRING>"

For example, if you are using default settings:

CMD

dotnet sql-cache create "Data Source=localhost;Initial Catalog=starter-kit;Integrated Security=True;TrustServerCertificate=True" dbo DistributedCache

Our database is now ready, and we can proceed to seed it with initial data. To do this, run tools/seeds.sql using your favorite SQL editor (note that you will need to replace some macros with real values). The script will create initial data, including creating an initial admin with the email you specify and the password "Password123".

Next, let's move on to setting up the Frontend.

Navigate to src/StarterKit/StarterKit.Identity/ClientApp and run the following commands (in most cases, this only needs to be done once, as the Identity Web App rarely changes and is hosted by the Identity Server):

CMD

yarn install
yarn build

You'll need to execute the same commands in src/StarterKit/StarterKit.App.Api/ClientApp:

CMD

yarn install
yarn build

The setup is now complete, and you can proceed to launch the application.