On this page

Guide

Hosting your own server

Installation

Install the .NET SDK for your platform. Then, install the EF Core tools for the .NET CLI.

dotnet tool install --global dotnet-ef

Clone the project

git clone https://github.com/unshackled-studio/Unshackled.Studio.git Unshackled.Studio

Running Unshackled Kitchen

Go to the directory for the Kitchen projects

cd Unshackled.Studio/src/Kitchen

Create app setting files

Copy and rename the sample-appsettings.json files for the Blazor server and client projects

Windows

copy .\Unshackled.Kitchen.My\sample-appsettings.json .Unshackled.Kitchen.My\appsettings.json
copy .\Unshackled.Kitchen.My\sample-appsettings.Development.json .\Unshackled.Kitchen.My\appsettings.Development.json
copy .\Unshackled.Kitchen.My.Client\wwwroot\sample-appsettings.json .\Unshackled.Kitchen.My.Client\wwwroot\appsettings.json
copy .\Unshackled.Kitchen.My.Client\wwwroot\sample-appsettings.Development.json .\Unshackled.Kitchen.My.Client\wwwroot\appsettings.Development.json

Mac OS/Linux

cp ./Unshackled.Kitchen.My/sample-appsettings.json ./Unshackled.Kitchen.My/appsettings.json
cp ./Unshackled.Kitchen.My/sample-appsettings.Development.json ./Unshackled.Kitchen.My/appsettings.Development.json
cp ./Unshackled.Kitchen.My.Client/wwwroot/sample-appsettings.json ./Unshackled.Kitchen.My.Client/wwwroot/appsettings.json
cp ./Unshackled.Kitchen.My.Client/wwwroot/sample-appsettings.Development.json ./Unshackled.Kitchen.My.Client/wwwroot/appsettings.Development.json

Configure app settings

Open the solution file or project folder in your favorite editor and complete the newly created appsettings files.

Unshackled.Kitchen.My/appsettings.json

"DbConfiguration": {
	"DatabaseType": "sqlite",
	"TablePrefix": "uk_"
}

DatabaseType: The database you will be using. Use sqlite, mssql, mysql, or postgresql as the value. Only database migrations for Sqlite are provided.
TablePrefix: The table name prefix in the database. Recommend that you leave this as "uk_" unless you have a reason to change it. If you do change it, you will need to remove the existing database migrations and create new ones.

"HashIdConfiguration": {
	"Alphabet": "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890",
	"Salt": "randomstringofcharacters",
	"MinLength": 12
},

Alphabet: The list of possible characters to use while hashing database IDs for display in URLs.
Salt: A random string of characters to salt your hash. Make this sufficiently long (at least 15 chars)
MinLength: The minimum length you want the resultant hash to be. Larger IDs may produce longer hashes, but lower ID numbers will not fall below this minimum.

"SiteConfiguration": {
	"SiteName": "Unshackled Kitchen",
	"AppThemeColor": "#236441",
	"AllowRegistration": true,
	"RequireConfirmedAccount": true,
	"ApplyMigrationsOnStartup": true,
	"PasswordStrength": {
		"RequireDigit": true,
		"RequireLowercase": true,
		"RequireNonAlphanumeric": true,
		"RequireUppercase": true,
		"RequiredLength": 10,
		"RequiredUniqueChars": 7
	}
}

SiteName: The default title of your app.
AppThemeColor: The color of the loading screen when your PWA is first displayed.
AllowRegistration: True, allows users to register for an account. False, prevents new user accounts registration.
RequireConfirmedAccount: True, requires new users to confirm their email adddress before logging in. False, new users can log in immediately.
ApplyMigrationsOnStartup: True, any new database migrations will be applied when the app starts. False, new will not be auto applied. You will need to apply them yourself.
PasswordStrength: Set the requirements you want for password strength.

"SmtpSettings": {
	"Host": "smtp.host.domain",
	"Port": 587,
	"UseSSL": true,
	"DefaultReplyTo": "email@domain.com",
	"Username": "",
	"Password": ""
}

Host: Your SMTP host URL.
Port: 587 is the default. 465 if required by your host. 25 if your host doesn't support SSL
UseSSL: Leave to true unless required otherwise.
DefaultReplyTo: The default reply address to be used when sending emails.
Username: Your host username.
Password: Your host password.

The Username and Password settings should be moved to a secrets file, key vault, or environment variable.

"ConnectionStrings": {
	"DefaultDatabase": "Data Source=Data/unshackled-kitchen.sqlite"
}

DefaultDatabase: The connection string for the database you chose in the DbConfiguration section. Defaults to a Sqlite database.

Unshackled.Kitchen.My.Client/wwwroot/appsettings.json

"ClientConfiguration": {
	"SiteName": "Unshackled Kitchen"
}

SiteName: The default title of your app.

Database Migrations

If you have changed databases or the table prefix, you will need to create new database migrations. In your terminal, move to the Unshackled.Kitchen.Core.Data directory.

cd ./Unshackled.Kitchen.Core.Data

Add a migration for the current release and your database.

Sqlite

dotnet ef migrations add v3.0.0 -c SqliteDbContext -s ../Unshackled.Kitchen.My -o Migrations/Sqlite

MS SQL Server

dotnet ef migrations add v3.0.0 -c MsSqlServerDbContext -s ../Unshackled.Kitchen.My -o Migrations/MSSQL

MySQL Server

dotnet ef migrations add v3.0.0 -c MySqlServerDbContext -s ../Unshackled.Kitchen.My -o Migrations/MySQL

PostgreSQL Server

dotnet ef migrations add v3.0.0 -c PostgresSqlServerDbContext -s ../Unshackled.Kitchen.My -o Migrations/PostgreSQL

Apply the migration

Sqlite

dotnet ef database update --context SqliteDbContext -s ../Unshackled.Kitchen.My

MS SQL Server

dotnet ef database update --context MsSqlServerDbContext -s ../Unshackled.Kitchen.My

MySQL Server

dotnet ef database update --context MySqlServerDbContext -s ../Unshackled.Kitchen.My

PostgreSQL Server

dotnet ef database update --context PostgreSqlServerDbContext -s ../Unshackled.Kitchen.My

Start the server

Move to the Unshackled.Kitchen.My directory from the main project directory.

cd ./Unshackled.Kitchen.My

Start the server. By default, the website will run at https://localhost:5580. You can change these settings under Properties/launchSettings.json.

dotnet run

Upgrading to new versions

Review the release notes for the new version (and any previous versions you may have skipped) to see if new database migrations are required. Add and apply new migrations using the same commands as before while changing the version number to the new version.