SQL Server Setup

Tagnet uses SQLite by default, which works well for single-server deployments. If your organization already runs SQL Server infrastructure, or you need to support multiple Tagnet instances sharing a common database server, this guide walks you through pointing Tagnet at a SQL Server database using the Database Setup page in the Tagnet Admin Console.

When to use this guide

Use this guide if:

• You have an existing SQL Server instance and prefer to keep all application databases in one place.
• Your organization's backup and DR strategy is built around SQL Server and you want Tagnet's database included.
• You are running Tagnet in a hosted or multi-tenant environment where SQLite's single-file model is not suitable.

SQLite remains the right choice for most single-server, on-premises installs. It requires no external infrastructure, has no additional permissions to configure, and performs well at typical Tagnet data volumes.

Prerequisites

Before you start, verify the following:

• SQL Server 2016 or later: Tagnet requires version 13.x or higher. Earlier versions lack features the EF Core migrations depend on.
• The target database already exists: Tagnet does not request dbcreator or sysadmin rights. Create the database manually in SQL Server Management Studio or with CREATE DATABASE before running this guide.
• Your account has the required permissions on the target database: either membership in the db_owner role, or both the CREATE TABLE and ALTER ANY SCHEMA permissions. The Admin Console tests with your current Windows identity.
• Collation: a case-insensitive collation (one containing _CI_ in the name, such as SQL_Latin1_General_CP1_CI_AS) is strongly recommended. Tagnet's queries assume case-insensitive matching; case-sensitive or binary collations will produce unexpected "not found" results on lookups that differ only by case.

Windows Authentication caveat

The Database Setup page tests the connection using your current Windows identity, the account you are logged in as when running the Admin Console elevated. This is not the account that will connect at runtime. The Tagnet Windows service runs as NT AUTHORITY\LocalService by default, and LocalService almost certainly does not have access to your SQL Server.

Windows Authentication against SQL Server means running the Tagnet service as an account SQL Server recognises: a domain account, or a group Managed Service Account (gMSA), with the required permissions on the Tagnet database. The Admin Console's Service Account page configures this: it checks the account, grants it what the service needs, reconfigures the service, and restarts it. Set the account there before switching this page to Windows Authentication; the Windows Authentication option shows which account the service runs as now. The account you set is preserved across Tagnet upgrades.

Choosing between the two: a gMSA needs a domain controller reachable whenever the Tagnet server restarts, and a domain account does not; see If a domain controller is not available at startup.

If you are not sure, use SQL Server Authentication with a dedicated SQL login. The credentials are stored in appsettings.Production.json (admin-only file) and used by the service at runtime.

Running the service as a domain account or gMSA

The Service Account page does all of the following in one save. The manual procedure remains here for servers administered without the console.

1. Create the SQL Server login for the account and grant it the permissions listed under Prerequisites. A gMSA login uses the account name with its trailing $, for example CREATE LOGIN [CORP\svc-tagnet$] FROM WINDOWS.
2. For a gMSA, install it on the Tagnet server first: Install-ADServiceAccount svc-tagnet, then confirm with Test-ADServiceAccount svc-tagnet. Your Active Directory administrator creates the account and authorises this server to retrieve its password; there is no password for you to handle.
3. Grant the account Full control on C:\ProgramData\Stratum Global\Tagnet. The installer sets permissions on the data and logs subfolders and on appsettings.Production.json separately, so grant the account on each of those as well rather than relying on inheritance.
4. In services.msc, open the properties of Tagnet System Service, switch to the Log On tab, and select This account. Enter the domain account and its password, or the gMSA name with both password fields left empty. Setting the account here also grants it the Log on as a service right.
5. If HTTPS is configured, grant the account read access to the certificate's private key: on the Web Server Setup page, click Validate, then Grant key access if it is flagged.
6. Restart the service and confirm it reaches Running. If it does not, the Tagnet log in C:\ProgramData\Stratum Global\Tagnet\logs names the cause: a logon failure points at the password or the gMSA installation, a SQL error at the login or its permissions.

Tagnet upgrades re-apply whatever account the service is registered under and never read or store its password, so this configuration is done once. If your domain assigns the Log on as a service right through Group Policy, add the account to that policy too; otherwise the next policy refresh removes the local grant and the service stops starting.

Walkthrough

1. Open Database Setup

1. Launch Tagnet Admin Console from the Start Menu or desktop shortcut.
2. Click Database Setup in the left navigation.
3. If the page shows a Restart as administrator prompt, click it. The console relaunches elevated via UAC and returns directly to the Database Setup page. Both writing the configuration file and restarting the Tagnet service require administrator rights.

A banner at the top of the form shows what Tagnet is currently configured to use, independent of the form selection.

2. Select SQL Server

Click the SQL Server radio button. The form expands to show the SQL Server connection fields.

3. Fill in the connection details

Field	Required	Description
Host	Yes	Hostname or IP address of the SQL Server (e.g. sql-prod-01 or 192.168.1.50)
Instance	No	Named instance, if applicable (e.g. SQLEXPRESS). Leave blank for the default instance.
Port	No	TCP port if SQL Server is not on the default 1433. Leave blank to use the default.
Database	Yes	Name of the target database. The database must already exist.
Authentication	Yes	Windows Authentication or SQL Server Authentication (see caveat above)
Username / Password	SQL Auth only	SQL login credentials. Not shown when Windows Authentication is selected.

4. Test the connection

Click Test connection. The Admin Console connects to SQL Server and runs six checks in sequence. If the connectivity check fails, the remaining five checks are shown as skipped (greyed out).

What each check verifies

Check	What it tests	Pass / Warning / Fail
Connectivity	Can open a connection to the specified host, instance, port, and database	Fail on network errors, wrong database name, or login failure
SQL Server version	ProductVersion is 13.x (SQL Server 2016) or later	Fail if below 13.x
Edition	Detects Standard, Developer, Enterprise, Express, etc.	Warning for Express (10 GB database size limit, memory and core limits)
Permissions	Account is db_owner, or has both CREATE TABLE and ALTER ANY SCHEMA	Fail if neither condition is met
Collation	Database collation contains _CI_ (case-insensitive)	Warning for _CS_ (case-sensitive) or _BIN / _BIN2 (binary) collations
Schema	Whether the database is empty, an existing Tagnet database, or has other tables. For a Tagnet database, whether this version of Tagnet can use it	Warning if tables exist but no EF migrations history table is found, if the history is empty, or if your account cannot read it. Fail if a newer version of Tagnet has upgraded the database, or if its migration history is not from Tagnet

Interpreting results

Express edition warning: Express is not a failure. Tagnet will work on Express, but be aware of the 10 GB per-database ceiling and the 4-core / 1410 MB memory limits. For production installs with active readers generating high tag-read volumes, those limits can become binding over time.

Collation warning: If the check reports a _CS_ or _BIN collation, tag EPC lookups and item queries that differ only in case will not match. You can change the collation of an empty database with ALTER DATABASE ... COLLATE ... before proceeding; changing the collation of a populated database requires exporting and reimporting data.

Schema warning: "Database has tables but doesn't appear to be a Tagnet database": This means the target database has user tables but no EF migrations history table. Verify you have entered the correct database name. Saving this configuration and restarting Tagnet will cause Tagnet to attempt to run migrations against an unrelated database, which may fail or produce unexpected results.

Schema pass: "Tagnet database, up to date with this version": The database already contains a Tagnet schema at exactly the version you have installed. This is the expected result when you reconfigure a Tagnet server that was previously pointed at this database.

Schema pass: "Tagnet database, N schema updates behind this version": The database was last used by an older version of Tagnet. Tagnet applies the updates automatically when the service starts. Take a backup of the database first if you have not already.

Schema fail: "The database was upgraded by a newer version of Tagnet": Another installation running a newer version of Tagnet has already upgraded this database. Tagnet cannot run against a database newer than itself, and the service will refuse to start if you save anyway. Install the newer version of Tagnet on this server, or restore the database from a backup taken before the upgrade. Tagnet never downgrades a database.

Schema warning: "Tagnet started creating its schema in this database, but the first start did not finish": An earlier first start against this database stopped partway, often on a permissions error. Tagnet tries again when it starts. If it fails again, check the service log for the reason.

Schema warning: "Its update history could not be read": The database has a Tagnet schema, but the account you are testing with cannot read it, so the console cannot tell whether this version of Tagnet can use it. Save is still allowed, and the service repeats the check when it starts. Grant your account read access and test again for a definite answer.

Schema fail: "Database has a migration history, but none of it is from Tagnet": The database belongs to another application that uses the same migration tooling. Check the database name, or create an empty database for Tagnet.

5. Save and restart

Once you are satisfied with the check results (no failures, and any warnings are understood), click Save and restart.

The console runs validation one more time with the current form values, then:

1. Writes appsettings.Production.json with the new DatabaseProvider and ConnectionStrings:DefaultConnection values.
2. Stops the TagNet Windows service (up to 60 seconds).
3. Starts the TagNet Windows service (up to 60 seconds). On first start with a new database, Tagnet runs EF Core migrations to create the schema. This can take a few seconds on a cold machine.

A progress bar and status messages track each step. When the service is running, a green success banner appears and the "Currently configured" banner at the top of the form updates to reflect the new SQL Server configuration.

Note: Save aborts without writing the file if any check reports a failure. Fix the highlighted issues and try again. Warnings do not block the save.

Switching back to SQLite

1. Open Database Setup (elevated).
2. Click the SQLite radio button.
3. The path field pre-fills with the default SQLite database location (C:\ProgramData\Stratum Global\Tagnet\data\app.db). Use Browse to select a different file if needed.
4. Click Test connection to verify the path and file.
5. Click Save and restart.

Tagnet restarts pointing at the SQLite file. Your SQL Server database is unaffected. You can switch back to it later using the same steps above.

What gets written to disk

Save and restart updates exactly two keys in appsettings.Production.json:

{
  "DatabaseProvider": "SqlServer",
  "ConnectionStrings": {
    "DefaultConnection": "Data Source=sql-prod-01;Initial Catalog=TagnetDB;..."
  }
}

All other keys in the file (Kestrel port, logging configuration, and anything else you have manually added) are preserved unchanged. The file is written atomically (temp file then swap) and the ACL is re-hardened to admin-only after each write.

The connection string stored in appsettings.Production.json is the runtime string used by the Tagnet service. It is different from the validation string used by the Admin Console: the persisted string does not include ApplicationName=Tagnet Admin Console, so SQL Server Activity Monitor shows Tagnet service connections cleanly.

Troubleshooting

Connectivity check fails

Error code	Likely cause	Fix
4060	Database does not exist, the account has no access to it, or it exists but is not online yet (SQL Server is still starting up or recovering it, or it was taken offline)	Create the database, or grant the account at minimum CONNECT permission. A database that is starting up or offline needs no action from Tagnet's side: the service waits for it at startup and logs a warning while it does
18456	Login failed: wrong username, password, or the login does not exist on this server	Verify the SQL login exists on the target SQL Server instance
-2, 11001, 10060	Network unreachable: host name won't resolve, wrong port, SQL Server not listening on TCP/IP	Confirm the host, instance, and port; enable TCP/IP in SQL Server Configuration Manager if needed

Save fails partway through

If the console reports "Configuration written, but the service could not be stopped" or "the service failed to start," the new appsettings.Production.json is already on disk. The status message describes which step failed:

• Stop failure: Another process may be holding the service in a pending state. Stop the service from the Services page (or services.msc), then use Save and restart again (the write step will be a no-op since the file is already correct) or start the service from the Services page.
• Start failure / timeout: The service could not reach the Running state within 60 seconds. The most common cause is a connection string that works for the Admin Console's identity but not for the service account. Check the Tagnet logs at C:\ProgramData\Stratum Global\Tagnet\logs for the specific error. With Windows Authentication, this almost always means the service account does not have SQL Server access. See the Windows Authentication caveat above.

Service starts but Tagnet cannot connect at runtime

If the service starts but the Tagnet web UI shows a database error or fails to load:

1. Open App Settings in the Admin Console (elevated) to confirm the connection string that was written.
2. Check the Tagnet logs for the specific ADO.NET or EF Core exception.
3. With SQL Server Authentication, verify the stored credentials are still valid. SQL logins can be disabled or have their passwords rotated independently of the Admin Console.
4. With Windows Authentication, confirm the service is running as the expected account in services.msc and that account has the required SQL permissions.