Step 1: Register Environment
Use the Nodinite Portal wizard to register your Environment and generate the installation package for the v6 to v7 migration. The wizard uses the same six steps as a fresh install — the portal appearance is almost identical. Migration-specific differences are called out in each step below.
Note
->
Only Windows Server (IIS) to Windows Server (IIS) migration is supported by this guide. Container-based runtimes are not supported for v6 to v7 migration.
Prerequisites
- Portal account with access to your Customer
- Valid Nodinite 7 product key
- Environment name, service accounts, database server, and existing v6 Configuration Database name
- Path to the existing v6 installation (e.g.,
C:\Program Files\Nodinite\<EnvironmentName>\) - DacFX installed on the target server
Open the Portal Wizard
Navigate to the Nodinite Portal
Navigate to your Customer entry
Ensure you have a Nodinite 7 product key:
- If missing, click Create Product Key
- Contact your Partner or Support page if needed
Click the Environment tab
Example of the 'Environments' tab showing registered Environments in the Portal.Click Add Environment
Example of the Add Environment button in the Portal.
Step 1: Basics
Example of the migration wizard navigation with the Basics step selected.
The Basics step sets the Environment identity and points the wizard at your existing v6 installation. The delivery platform is locked to Windows Server (IIS) — no other platform is available during v6 to v7 migration.
Example of the Basics tab showing the Upgrade from Nodinite 6 mode with environment details and the Legacy Nodinite 6 environment path field.
Environment Mode
The Environment Mode has two options:
- New Install - for fresh installations of Nodinite v7
- Upgrade from Nodinite 6 - for migrating an existing v6 environment to v7
Click Upgrade from Nodinite 6 - Clicking Upgrade from Nodinite 6 changes the wizard heading and step navigation labels to reflect the migration context. The portal now shows six steps: Basics, Auth, Infrastructure, Servers, Agents, and Review and Download.
Proceed to the next heading for details on adding the remaining required variables for the Basics step.
Basics Variables
| Variable | Default | Description |
|---|---|---|
| Environment Name* | Name of the target Environment. ⚠️ Reuse your v6 name exactly — this value is embedded in IIS site names, folders, and database references. | |
| Description | Optional purpose or usage description | |
| Destination Root Path | C:\Program Files\Nodinite |
Root installation directory for v7 |
| Legacy Nodinite 6 environment path* | e.g., C:\Program Files\Nodinite\DEV\ |
Full path to the existing v6 installation. Used for backup and legacy cleanup. |
Warning
The Environment Name is permanent. Once the environment is created and the installation is built around it, the name must not be changed. Changing it later can break IIS site naming, folder references, and database naming.
Once all required fields are complete, the Save and Next buttons become active:
Example showing Save and Next buttons enabled when all required configuration is complete.
Example showing Next button disabled when required configuration is incomplete.
Warning
If the Next button remains disabled, check all required fields (marked with *) to ensure they are filled in.
Click Next to proceed to the Auth step.
Step 2: Auth
Example of the migration wizard navigation with the Auth step selected.
Example of the Auth step showing Windows Authentication selected. OAuth2 is grayed out with a portal note: "Upgrade from Nodinite 6 starts with Windows auth."
Important
Only Windows Authentication is supported during v6 to v7 migration. The portal locks the auth mode to Windows auth for the initial migration. OAuth2 / OIDC can be configured after the first v7 deployment is verified.
Windows Settings
Enter information about the initial administrator account and domain defaults. The Portal uses these values to create the first user, which ensures that you can sign in to the Web Client after the installation is complete.
Example of the Windows settings section with administrator account and domain defaults.
| Mandatory | Variable | Default | Description |
|---|---|---|---|
| Authentication Method | Windows |
Uses Active Directory and integrated security | |
| Administrator domain | <DomainName> |
Domain prefix for account names | |
| Administrator account | <NodiniteAdminUserAccountName> |
Initial administrator account | |
| Administrator email | e.g., <nodiniteadmin@acme.com> |
Optional email. Populates the user entry and the Email alarm plugin. |
Service Account Defaults
Decide whether to use Domain mode or Workgroup mode and whether to use gMSA accounts. Domain mode is required for gMSA. The default is to use the same account for all services; individual overrides are available in Step 4: Servers.
Example of the Windows administrator domain input used when Windows auth is selected.
Example of the service account defaults section with domain and account name values for Windows services.
| Mandatory | Variable | Default | Description |
|---|---|---|---|
| Domain Name | <DomainName> |
Domain used for the default service account pattern | |
| Account Name | <DefaultServiceAccountName> |
Base account used by services unless overridden |
Note
gMSA accounts are supported directly on Nodinite Core Services in v7 (not only on agents). If you opt in to gMSA, the account name must end with the
$suffix. The Portal validates this and will not generate the package if the account name is invalid. gMSA accounts must be pre-provisioned in Active Directory before the installer runs.
Important
If you use custom domain service accounts for IIS-hosted v7 services, make sure matching Service Principal Names (SPN) exist before users start testing Windows authentication. The most common misses are the HTTP SPNs for Web Client and Web API hostnames, plus the SQL Server SPNs used by backend database connections.
Click Next to proceed to the Infrastructure step.
Step 3: Infrastructure
Example of the migration wizard navigation with the Infrastructure step selected.
The Infrastructure step is the only place where the environment records the SQL Server connection details, any SQL DB Lookup entries, and the outbound proxy settings used by the generated installation package. Registration itself is not a database configuration step.
For the new portal, the SQL connection string is mandatory and must be provided in one of two valid ways:
- Provide the full SQL connection string directly in the Portal
- Toggle the option to provide it as a parameter during install/update execution
Configure SQL Server Connectivity
Example of the database configuration section — enter the SQL Server connection details for the existing v6 database.
Important
In the new Portal, the user MUST either provide the full SQL connection string directly in this step or toggle the option to supply it as a parameter during install/update execution. The connection string is mandatory, and the portal validates it before you can proceed.
Important
In the Database Name field, you MUST provide the name of the EXISTING v6 Configuration Database. The migrated v7 environment will use this database. Double-check this value — it is critical. This is not a new database to create; it is the live v6 configuration database being reused.
Choose the database type that matches your deployment:
- SQL Server Standalone — Single SQL Server instance (Standard, Enterprise, Express, failover clusters)
- Always On Availability Group — SQL Server Always On Availability Group
- Azure Managed Instance — Azure SQL Managed Instance
Example of the SQL Server connection string prompt — provide the full connection string or choose to supply it during install/update execution.
| Variable | Default | Description |
|---|---|---|
| Database Type | Standalone | SQL Server deployment model |
| Database Server Name | localhost |
SQL Server instance (use ServerName\InstanceName for named instances) |
| Database Name | NodiniteConfig_<EnvironmentName> |
EXISTING v6 Configuration Database name |
| Sql Package Path | C:\Program Files\Microsoft SQL Server\170\DAC\bin\SqlPackage.exe |
Path to SqlPackage.exe. DacFX must be installed. |
Note
For detailed information about connection string formats, certificate validation, encryption settings, Always On Availability Groups, and troubleshooting, see SQL Server Connection Strings.
Configure SQL DB Lookup
Tip
This is an optional configuration. Only configure SQL DB Lookup if you need the Nodinite sqllookup Formula plugin.
Use the SQL DB Lookup section when you want Search Field Expressions to query reference tables from SQL Server with the sqllookup Formula plugin.
Example of the SQL DB Lookup section with named connection string entries for Formula expressions.
Click + Add to create new connection string entries:
Example of the Add button that inserts a new SQL DB Lookup row in the Portal.
Each entry requires:
- Name — Connection string identifier used in sqllookup expressions (e.g.,
SqlDbLookupLocal) - Connection String — SQL Server connection string for the reference database
Tip
The name you configure here is the first parameter in sqllookup expressions. For example:
sqllookup('SqlDbLookupLocal', 'DatabaseName', 'TableName', ...)
Configure Network / Proxy
Tip
This is an optional configuration. Only configure it if your environment requires outbound HTTP proxy settings.
Example of the Network / Proxy section — define the proxy mode, URL, and bypass hosts for outbound HTTP.
The Network / Proxy section controls how the installer reaches outbound HTTP endpoints. Configure the proxy mode, proxy URL, and bypass hosts as required by your network.
Click Next to proceed to the Servers step.
Step 4: Servers
Example of the migration wizard navigation with the Servers step selected.
Before entering the Servers step, the portal shows a confirmation dialog for the existing v6 Configuration Database connection string:
Example of the confirmation dialog — verify the connection string matches your Nodinite 6 Config database before clicking Continue to servers.
Click Review connection string to go back and adjust, or Continue to servers to proceed.
Server Configuration
The Servers step is where server names, ports, and service account overrides are configured. The server name is set here — it is not part of the Basics step.
Example of the Servers configuration page showing the server list, service account toggle, and port values.
Selected Server
Enter the base host values:
- Server name — hostname of the target server
Important
Do NOT use
localhostas a server name. Use the actual machine name or FQDN of the host where the Core Services will be installed. This entry MUST match the name from agents configured locally on the server. - Install path — where Nodinite files will be installed on this host
- Host core services on this server — there must be exactly one server with Core Services enabled
Core Platform Services Ports
| Service | Default Port | Notes |
|---|---|---|
| Web Client | 40000 | TLS/port 443 configured separately in Step 11 |
| Web API | 40001 | |
| Log API | 40002 | |
| Logging Service | 40003 | |
| Monitoring Service | 40004 | |
| MCP Endpoint | 40005 |
Use custom ports only when required by conflicts or policy.
Per-Service Account Overrides
By default, all services use the account set in Step 2: Auth. Clear the Same account for all services toggle to enter per-service accounts.
Example of individual service account configuration after clearing the shared service-account option.
TLS Configuration
Important
We strongly recommend that Core Services run with TLS enabled. Review the Hardening guidance for additional TLS configuration recommendations.
Configure the TLS domain name and certificate thumbprint for the selected server host. The TLS domain name must match the certificate subject name or SAN values.
Agents on This Server
Important
Agents cannot be added during initial migration. The Agents section in the Servers step is intentionally deferred. Agents are imported from the monitoring agent JSON exported from the running Nodinite 7 Web Client after core services are installed.
Example of the "Agents on this server" section showing the deferred message: agents are imported after the core package is installed.
Click Next to proceed to the Agents step.
Step 5: Agents
Example of the migration wizard navigation with the Agents step selected.
As already mentioned, the Agents step is deferred during v6 to v7 migration. The portal shows a message indicating that agents will be imported after the core services are installed.
Example of the Agents step showing the deferred message: agents are imported after the core package is installed.
Click Next to proceed to the Review and Download step.
Step 6: Review and Download
The Review and Download step is the final validation point before the installation package is generated. All portal configuration (Steps 1–5) feeds into this step.
Review the environment architecture overview to confirm that all components, ports, service accounts, and the database connection are correct:
Example of the environment overview showing Core Services architecture with ports, service accounts, and database connections.
- Review all components (Web Client, Web API, Log API, Logging Service, Monitoring Service)
- Confirm port assignments match your configuration (defaults: 40000–40004)
- Verify service accounts are correct
- Confirm the database connection uses the existing v6 Configuration Database
If changes are needed, navigate back to the relevant step using the step buttons at the top of the wizard.
Note
The Next button in the portal remains disabled until the Core Services package has been downloaded at least once. You must click Download Core (or equivalent) before proceeding through the rest of the migration.
Proceed to Step 2: Review Configuration for the architecture overview, then Step 3: Download Binaries to download the installation package.
Completion Checklist
- Portal wizard opened and Upgrade from Nodinite 6 selected
- Step 1 Basics: Environment name matches v6, Legacy Nodinite 6 path entered
- Step 2 Auth: Windows auth confirmed, administrator account and service account defaults set
- Step 3 Infrastructure: Existing v6 Configuration Database name entered, connection string validated
- Step 4 Servers: Server name, ports, and service account overrides confirmed
- Step 5 Agents: Noted as deferred — will return after core services install
- Step 6 Review and Download: Architecture diagram reviewed, ready to download
Troubleshooting
Cannot Create Product Key
Problem: "Create Product Key" button is disabled or missing.
Solution:
- Verify you have a valid Nodinite 7 contract
- Contact your Partner for contract activation
- Support, read more on the Support page
Save Button Disabled
Problem: Cannot click Save button.
Solution:
- Check for validation errors (red text) in form fields
- Ensure all required fields (marked with *) are filled
- Verify product key is valid
Validation Errors
Problem: Portal shows validation errors after clicking Save.
Solution:
- Environment Name: Cannot contain special characters
- Ports: Must be unique and between 1–65535
- Database Server: Must be accessible from Portal
- Service accounts: Verify format (
Domain\Username, orDomain\Account$for gMSA)
Database Name Already Exists
Problem: Portal shows database name conflict.
Solution:
- Verify you are using the correct v6 database name
- Check SQL Server for the existing Configuration database
- Confirm you have not already migrated this environment