08Customization

You can change many things without code: the company name, the logo, the numbering, the labels, and the language. For colors, fonts, and email texts, you change the source code and publish the app again.

Translate the app or add a language

MaintDock shows English by default. Every text on the screen can be translated with a JSON file. The English text is the key, so English needs no file.

1. Open the Localization folder. On the server it is in the app folder (for example C:\inetpub\maintdock\Localization). In the source code it is src/MaintDock.Web/Localization.
2. Copy template.json to a new file named with the language code, for example de.json (German), fr.json (French), or es.json (Spanish). A code with a region also works, for example pt-BR.json.
3. Translate each value. Keep the key (the English text) as it is. Keep {0}, {1}, and so on in the text: MaintDock puts numbers and names there. Save the file as UTF-8.
   JSON

   {
     "Work orders": "Arbeitsaufträge",
     "{0} is overdue.": "{0} ist überfällig.",
     "Cancel": ""
   }

4. Restart MaintDock, so it reads the new file. (IIS: restart the site or recycle the application pool. Linux: sudo systemctl restart maintdock.) You do not need to rebuild the app.
5. Open Settings > General and pick the language under Language. The list shows English and each language that has a file in the Localization folder. Then click Save changes.

• An empty value or a missing key shows the English text. So you can translate step by step. In the example above, "Cancel" stays in English.
• If the file is not valid JSON, MaintDock ignores it and shows English. Check the file with a JSON checker.
• The language applies to all users. Numbers and month names follow the language. The date format stays as you set it in Settings.
• Docker: the translation files are inside the image. Put your file in source/src/MaintDock.Web/Localization/, then run docker compose build and docker compose up -d.
• After an update, the new template.json can have new texts. Compare it with your file and translate the new keys. Until then, they show in English.

Logo and company name

• Company name: Settings > General > Company name. It shows at the bottom of the menu, on the sign-in page, at the bottom of emails, on asset labels (when Show the company name is on), and at the top of the PDFs when no logo is uploaded.
• Logo: Settings > General > Logo. Upload a PNG or JPG file of up to 1 MB. It shows at the top of the work order, purchase order, and report PDFs, in place of the company name. Asset labels do not show the logo.
• The product name "MaintDock" at the top of the menu and in the browser tab is part of the code (src/MaintDock.Web/Components/Layout/MainLayout.razor, AuthLayout.razor, MobileLayout.razor, Features/Mobile/TodayPage.razor, and the page titles). The name of the installed phone app is in src/MaintDock.Web/wwwroot/manifest.webmanifest, and the name in the email header is in the EmailLayout class (see Email texts). The browser tab icon is src/MaintDock.Web/wwwroot/favicon.svg, and the phone app icons are in src/MaintDock.Web/wwwroot/icons/.

Colors and fonts

All colors, fonts, and sizes of MaintDock are CSS variables (tokens) at the top of src/MaintDock.Web/wwwroot/css/maintdock.css. The light mode values are in :root { ... }, and the dark mode values are in :root[data-mode="dark"] { ... }. The main tokens are:

The simplest way to change colors is to add your values at the end of src/MaintDock.Web/wwwroot/css/app.css. That file loads after maintdock.css, so your values win. Your changes also stay in one place, which makes updates easier. Set the dark mode values too:

/* My company colors */
:root {
  --accent: #2C6ECB;
  --on-accent: #FFFFFF;
  --accent-ink: #1F5AA8;
}
:root[data-mode="dark"] {
  --accent: #5B9BF0;
  --on-accent: #0E1114;
  --accent-ink: #5B9BF0;
}

Fonts: the font files are in src/MaintDock.Web/wwwroot/fonts/, and src/MaintDock.Web/Components/App.razor lists them (the Fonts list makes the @font-face rules). To use another font, add its .woff2 files, change the Fonts list, and set --font and --mono. PDF files use their own copy of IBM Plex in src/MaintDock.Infrastructure/Documents/Fonts/.

Publish the change. After you change a CSS file, build the app again and copy the result to your server, as described in Change the code and Updating:

cd source
dotnet publish src/MaintDock.Web -c Release -o ../publish

Email texts

• Notification emails use the same text as the in-app notification. The subject is that text too (cut after 90 characters). The button says Open in MaintDock. So a translation file also translates these emails.
• The sender (from address and from name) is set in Settings > Email (SMTP). The company name at the bottom of each email comes from Settings > General.
• The layout of all emails (the dark header with the name MaintDock, the amber button, and the company name at the bottom) is in the EmailLayout class in src/MaintDock.Infrastructure/Email/Email.cs.
• The invitation and password reset emails, with their button texts, are in src/MaintDock.Web/Components/Account/AccountServices.cs (the methods SendInvite and SendReset).
• The purchase order email to a vendor is in src/MaintDock.Web/Features/Purchasing/PurchaseOrderDocument.cs (the methods EmailSubject and EmailHtml).

Edit these files, then publish the app again.

Change the code

The full source code is in the source folder. Read the developer guide source/docs/development.md before you change it. It explains the rules that every screen follows: the design classes, the shared components, permissions, sites, translations, and the core services.

Project layout

Build and run

You need the .NET 10 SDK and a database. For development, MaintDock uses PostgreSQL by default (see src/MaintDock.Web/appsettings.Development.json).

cd source
dotnet build
cd src/MaintDock.Web
ConnectionStrings__Default="Host=localhost;Database=maintdock_dev;Username=postgres;Password=postgres" dotnet run

On Windows PowerShell, set the connection first with $env:ConnectionStrings__Default="Host=localhost;Database=maintdock_dev;Username=postgres;Password=postgres", then run dotnet run. To use SQL Server for development, also set Database__Provider to SqlServer and use a SQL Server connection string. To use SQLite, which needs no server, set Database__Provider to Sqlite and ConnectionStrings__Default to Data Source=App_Data/maintdock-dev.db.

Open http://localhost:5264. In Development, the app skips the wizard. On an empty database, it creates the tables, the admin [email protected] with the password Admin@12345, and the sample data. The other sample users have the password Demo@12345. To start again, drop the development database (with SQLite, delete the file).

Database changes

The entities are in src/MaintDock.Domain, and the table setup is in src/MaintDock.Infrastructure/Data/ModelConfiguration.cs. After you change an entity, add a migration for all three databases. Install the EF Core tool once with dotnet tool install -g dotnet-ef. Then run these three commands in the source folder:

dotnet ef migrations add <Name> --project src/MaintDock.Migrations.PostgreSql --startup-project src/MaintDock.Web --output-dir Migrations -- --provider PostgreSql
dotnet ef migrations add <Name> --project src/MaintDock.Migrations.SqlServer --startup-project src/MaintDock.Web --output-dir Migrations -- --provider SqlServer
dotnet ef migrations add <Name> --project src/MaintDock.Migrations.Sqlite --startup-project src/MaintDock.Web --output-dir Migrations -- --provider Sqlite

Replace <Name> with a short name, for example AddAssetColor. MaintDock applies new migrations by itself when it starts.

Tests, texts, and publishing

• dotnet test runs the tests. The database tests run on SQLite by default, so they need no server. To run them on PostgreSQL or SQL Server, set MAINTDOCK_TEST_PROVIDER to PostgreSql or SqlServer, and MAINTDOCK_TEST_CONNECTION to your server, for example Host=localhost;Username=postgres;Password=postgres.
• After you add or change text on the screen, run python3 tools/extract-strings.py. It updates template.json with every translatable text.
• To make new binaries, run dotnet publish src/MaintDock.Web -c Release -o ../publish. Copy the publish folder to your server as described in Updating.
• To build a Docker image, run docker build -t maintdock . in the source folder.