appsettings.json#

To configure the application, you can edit the appsettings.json file.

Navigate to RepositoryDir/.
If there is not a file named appsettings.json, then copy the appsettings.json.dist file to appsettings.json.
In the appsettings.json file, update the settings. Each of the available settings is described below.
Restart the application for the changes to take effect.

Settings are described below using their full path, with colons separating the levels of the JSON document. For example, Data:ColecticaRepository:ConnectionString refers to the ConnectionString property inside the ColecticaRepository object inside the Data object. Any setting can also be provided as an environment variable, replacing each colon with two underscores, for example Data__ColecticaRepository__ConnectionString. Environment variables override the values in the file.

Required Configuration Fields #

These settings must be configured in order for Colectica Repository to work.

DiskCachePath: The disk location on the server where cache files can be stored. Required unless the disk cache is disabled.
DiskCache:DisableCache: Set to true to disable the on-disk cache. The default is false.
Data:DefaultConnection:ConnectionString: The full connection string of the database to use to store authentication tables, user profiles, baskets, and custom pages.
Data:DefaultConnection:ProviderName: The name of the database provider. Either Microsoft.Data.SqlClient or Npgsql.
Data:ColecticaRepository:ConnectionString: The full connection string of the Colectica Repository database.
Data:ColecticaRepository:ProviderName: The name of the database provider. Either Microsoft.Data.SqlClient or Npgsql. The value System.Data.SqlClient used by earlier releases is no longer accepted.
UseWindowsAuthentication: Set to true if using Windows authentication; otherwise set to false. Setting true will also disable JWT token authentication in the REST application and Windows Authentication will be enabled. See Configure Active Directory.

See below for sample database connection strings.

SMTP Configuration #

SMTP configuration is used for sending notification emails, including password reset emails, account confirmation emails, feedback messages, and basket notifications. If configuration is not provided, emails will not be sent.

Smtp:Host: The host name of the SMTP server.
Smtp:Port: The port of the SMTP server. The default is 25.
Smtp:UserName: The user name used to authenticate with the SMTP server. If not specified, anonymous authentication will be attempted.
Smtp:Password: The password used to authenticate with the SMTP server. The password should not be stored here. Instead, set an environment variable named Smtp__Password.
Smtp:EnableSsl: Set to false to disable TLS. By default the connection security is negotiated automatically.
Smtp:ReplyTo: The email address to use as the sender.
Smtp:DisableCertificateRevocationCheck: Set to true to disable certificate revocation checks.
Smtp:DisableCertificateValidation: Set to true to disable certificate validation.
Smtp:MaxSendRatePerSecond: The maximum number of messages sent per second. The default is 1.

Home Page Configuration #

Most home page content is configured by the administrator in Site Information. The following optional settings are only available in appsettings.json.

Home:TopicalConceptSystem:Agency: The agency identifier of the Concept System whose top level concepts are displayed as topics on the home page.
Home:TopicalConceptSystem:Identifier: The unique identifier of the Concept System to display on the home page.
Home:Item:Agency: The agency identifier of an item whose full content is displayed on the home page.
Home:Item:Identifier: The unique identifier of an item whose full content is displayed on the home page.
Home:RedirectUrl: If set, requests for the home page are redirected to this URL.

Elasticsearch Configuration #

Elasticsearch can be used for the web portal’s search page. See Elasticsearch Indices and Elastic Indexer.

Elasticsearch:Enabled: Set to true to enable Elasticsearch for the the portal search page. Set to false to use the built-in database search.
Elasticsearch:Host: The hostname and port used to access the Elasticsearch server (e.g., http://localhost:9200).
Elasticsearch:IndexName: The prefix of the Elasticsearch index. The index name will be {prefix}_registered_item.
Elasticsearch:ApiId, Elasticsearch:ApiKey: Optional API key credentials used to authenticate with the Elasticsearch server.
Elasticsearch:EnableApiVersioningHeader: Set to true to enable the API versioning header in Elasticsearch requests. This allows using Elasticsearch 8.x servers.

Logging Configuration #

Logging:LogLevel: The level of ASP.NET Core log messages to be included. Options are Error, Warning, Information, Debug.
Serilog:LogLevel: The level of Colectica Repository messages to be included. Options are Error, Warning, Information, Debug, Verbose. The environment variable COLECTICA_LOG_LEVEL overrides this setting.
Serilog:DiskLocation: The path on disk at which Colectica Repository log files will be stored. The default is the logs directory inside the application directory. The environment variable COLECTICA_LOG_LOCATION overrides this setting.
Serilog:StructuredDiskLocation: If specified, the path on disk at which JSON structured log files will be stored. These files can be aggregated by logstash or other systems.
Serilog:HttpLocation: If specified, the URL to which structured logs will be POSTed. This can be used to send logs to logstash or other log aggregation systems.

See Observability for more information.

Repository Settings #

The RepositorySettings section controls the behavior of the repository and the web portal.

Features#

RepositorySettings:Features:EnableSchemaValidation: If true, validate items against the format’s XML schema, and fail with error code R0023 if not valid.
RepositorySettings:Features:EnableItemReferenceValidation: If true, validate that any items referenced by the item being registered exist in the repository.
RepositorySettings:Features:SynchronizeExternalRoles: If true, set user roles provided via OpenID Connect or Azure AD to the internal roles store. Roles not present in the token are removed from the user.
RepositorySettings:Features:EnableUserSuppliedVersionResponsibility: If true, the version responsibility supplied by the client when registering an item is kept. If false, the version responsibility is set to the name of the authenticated user.
RepositorySettings:Features:EnableItemDeletion: If true, administrators can permanently delete items using the REST API. If false, deletion requests fail with error code R0025.
RepositorySettings:Features:EnableAdvancedSearch: If true, items are indexed for the advanced search API when they are registered. This feature requires PostgreSQL.
RepositorySettings:Features:EnableBasedOnIndexing: If true, the “based on” relationships between items are indexed when items are registered, so they can be used in relationship searches.
RepositorySettings:Features:DisableValidationDetailsReports: If true, details of request deserialization errors are omitted from REST API error responses.

The feature settings are copied to the repository database when the application starts, so that command line tools such as the Elastic Indexer and the Repository CLI use the same settings.

HTTP#

RepositorySettings:Http:CspEnable: Indicates whether Content Security Policy (CSP) is enabled. Set to true to enable CSP.
RepositorySettings:Http:CspHeader: Specifies the Content Security Policy header value. The token 'nonce-generated' is replaced with a unique nonce for each request. Example: default-src 'self'; script-src 'self' 'unsafe-eval' 'nonce-generated'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; object-src 'none'; base-uri 'self'.
RepositorySettings:Http:XFrameOptionsEnable: Indicates whether the X-Frame-Options header is enabled. Set to true to enable the X-Frame-Options header.
RepositorySettings:Http:XFrameOptions: Specifies the value for the X-Frame-Options header. Example: SAMEORIGIN.
RepositorySettings:Http:XContentTypeOptionsEnable: Indicates whether the X-Content-Type-Options header is enabled. Set to true to enable the X-Content-Type-Options header.
RepositorySettings:Http:HttpsRedirectEnable: Indicates whether HTTP requests should be redirected to HTTPS. Set to true to enable HTTPS redirection.
RepositorySettings:Http:HttpsRedirectPort: Specifies the port to which HTTP requests should be redirected. Set to 443 for standard HTTPS redirection.
RepositorySettings:Http:StrictTransportSecurityEnable: Indicates whether HTTP Strict Transport Security (HSTS) is enabled. Set to true to enable HSTS.
RepositorySettings:Http:StrictTransportSecurityMaxAge: Specifies the max-age directive for HSTS in seconds. Set to 31536000 (1 year) to enforce HSTS for one year.
RepositorySettings:Http:StrictTransportSecurityIncludeSubDomains: Indicates whether the HSTS policy applies to subdomains. Set to true to include subdomains in the HSTS policy.
RepositorySettings:Http:StrictTransportSecurityIncludePreload: Indicates whether the HSTS policy includes the preload directive. Set to false to exclude the preload directive.
RepositorySettings:Http:ReferrerPolicyEnabled: Indicates whether the Referrer-Policy header is enabled. Set to true to enable the Referrer-Policy header.
RepositorySettings:Http:ReferrerPolicy: Specifies the value for the Referrer-Policy header. Example: strict-origin-when-cross-origin.
RepositorySettings:Http:SetHostCookiePrefix: Indicates whether to set the __Host- cookie prefix on the login cookie. When enabled, the site must be served over HTTPS. Set to false to disable the host cookie prefix.

Portal#

RepositorySettings:Portal:DisplayVersionResponsibility: Indicates whether the version responsibility should be displayed. Version responsibility may include identifying information such as email addresses. Set to false to hide the version responsibility.
RepositorySettings:Portal:DisplayVersionRationale: Indicates whether the version rationale should be displayed. Version rationale may include information about the changes made in a version as recorded in the log message when items are registered with the repository. Set to false to hide the version rationale.
RepositorySettings:Portal:DisableSwaggerUI: Indicates whether the Swagger documentation for the included REST API should be disabled. Set to false to enable the Swagger UI.
RepositorySettings:Portal:AllowAdditionalTagsOnCustomPages: Specifies additional HTML tags that are allowed on custom pages. By default, many tags are stripped from custom pages to prevent security vulnerabilities. Set to an empty array [] to disallow additional tags.
RepositorySettings:Portal:EnableBasketNotifications: If true, users can subscribe to email notifications for their baskets. Once per hour, the portal checks for new versions of the items in subscribed baskets and emails the basket owners. Requires SMTP configuration and RepositorySettings:Portal:BaseUrl.
RepositorySettings:Portal:BaseUrl: The public URL of the portal, including a trailing slash, for example https://www.example.com/. Used to build links in notification emails.
RepositorySettings:Portal:EnableLoggingKnownPII: If true, information that may identify users, such as user names, is included in log messages.
RepositorySettings:Portal:Lineage:MaxSourceDepth: The number of levels of source variables and questions shown in the variable lineage graph. The default is 4.
RepositorySettings:Portal:Lineage:MaxSuccessorDepth: The number of levels of derived variables shown in the variable lineage graph. The default is 2.
RepositorySettings:Portal:Lineage:MaxNodes: The maximum number of items drawn in the variable lineage graph. The default is 150.
RepositorySettings:Portal:Lineage:CollapseSiblingsAbove: When an item has more than this number of sources or successors, the group is collapsed. The default is 12.

HealthChecks#

The health check endpoint at /healthz reports Unhealthy when free disk space falls below these thresholds.

RepositorySettings:HealthChecks:MinimumFreeDiskCacheMegabytes: Specifies the minimum amount of free disk space (in megabytes) required for the cache. The default is 500.
RepositorySettings:HealthChecks:MinimumFreeDiskLogMegabytes: Specifies the minimum amount of free disk space (in megabytes) required for logs. The default is 250.

General#

RepositorySettings:RepositorySecurityMode: Specifies the security mode for the repository. Possible values are Disabled, Permissive, and Enforcing. See Security Modes.
RepositorySettings:CommandTimeoutInSeconds: Specifies the timeout for database commands in seconds. The default is 360.

Workflow Configuration #

Colectica Repository can be configured to connect to Colectica Workflow Services. When enabled, the /api/v1/replication REST API endpoints forward replication requests to the workflow server.

Workflow:Enabled: Indicates whether the workflow functionality is enabled. Set to false to disable workflow functionality.
Workflow:WorkflowServer: Specifies the URL of the workflow server.
Workflow:ServerId: Specifies the server ID for the workflow server. Each repository connected to a workflow server should have a unique server ID. Example: ColecticaRepositoryPublic.
Workflow:ApiKey: Specifies the API key used to authenticate with the workflow server. The API key must be a string that is at least 16 characters long.
Workflow:UseWindowsAuthentication: Indicates whether to use Windows authentication for the workflow server. Set to false to disable Windows authentication.

Workflow Preview Configuration #

Colectica Repository can be deployed as a workflow preview site that allows users to preview the results of workflow replications before approving them. A preview site opens a temporary database for each replication request instead of the repository database.

WorkflowPreview:IsWorkflowPreview: Indicates whether the workflow preview functionality is enabled. Set to false to disable workflow preview functionality.
WorkflowPreview:WorkflowPreviewFilePath: Specifies the file path for storing workflow preview databases.

File Storage Configuration #

File storage is used for attachments referenced by items, such as external instrument files.

FileStorage:Enabled: Indicates whether file storage is enabled. Set to true to enable file storage functionality.
FileStorage:StorageType: Specifies the type of storage to use. Possible values are LocalDisk and WebDAV.
FileStorage:MaxUploadSize: Specifies the maximum upload size in bytes. Set to 104857601 to allow uploads up to approximately 100 MB. When hosting in IIS, also set maxAllowedContentLength in Web.config.
FileStorage:LocalDisk:StoragePath: Specifies the path on the local disk where files will be stored.
FileStorage:WebDAV:StorageUri: Specifies the URI of the WebDAV storage.
FileStorage:WebDAV:Username: Specifies the username for accessing the WebDAV storage.
FileStorage:WebDAV:Password: Specifies the password for accessing the WebDAV storage.

Geolocation Configuration #

Custom data extracts downloaded from baskets can be blocked for requests from certain countries. This requires a MaxMind GeoIP2 country database.

Geolocation:Enabled: Set to true to enable country checks on data downloads.
Geolocation:CountryDatabasePath: The path on disk of the GeoIP2 country database file.
Geolocation:ProhibitDataDownloadISOCodes: An array of ISO country codes from which data downloads are refused. If the country of a request cannot be determined, the download is refused.

OpenTelemetry Configuration #

To use OpenTelemetry for monitoring and tracing, configure the following settings. Additionally, the standard environmental variables need to be set for OpenTelemetry to work. For more information, refer to the OpenTelemetry documentation: https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/

OpenTelemetry:Enabled: Indicates whether OpenTelemetry is enabled. Set to false to disable OpenTelemetry functionality.

MCP Configuration #

Mcp:TimeoutSeconds, Mcp:RateLimitPerMinute: See MCP Server for details.

Miscellaneous Configuration #

SupportedLanguages: A list of languages supported by the user interface. By default this is "en-US", "fr", "fr-CA", "de". To add support for additional languages, see Localization, and then update this property.
Language: The default language of the user interface. Built-in options are en-US, fr, fr-CA, and de.
ForwardedHeadersEnabled: Enable inspection of X-Forwarded-* headers for use behind an HTTP proxy or load balancer.
XForwardedForDisabled: Disable inspection of the X-Forwarded-For header.
DefaultAdminUser: If set, the user with the specified email address will be granted administrator privileges when the application starts.
DefaultNewUserRole: If set, the specified role will be added to new user registrations and external logins. The default is ColecticaGuest.
Admin:ExternalDashboardUrl: The URL of an external dashboard. If set, a button linking to the URL will be included in the Colectica Portal administrator dashboard.
EntityFramework:ApplicationDbContext:ConnectionStringKey: Used by ASP.NET core. This value should not be changed.

Open ID Connect Configuration #

OpenIDConnect:*: See Configure OAuth2 OpenID Connect (OIDC) for details.

Local JWT Token Configuration #

LocalJwtProvider:*: See Configure Local JWT Token Provider (Optional) for details.

Identity Password Policies #

When using database-managed user accounts, the following settings can be used to configure password policies.

IdentityPasswordPolicy:RequireDigit: Indicates whether a password must contain at least one numeric digit (0-9). Set to true to enforce this requirement.
IdentityPasswordPolicy:RequireLowercase: Indicates whether a password must contain at least one lowercase letter (a-z). Set to true to enforce this requirement.
IdentityPasswordPolicy:RequireUppercase: Indicates whether a password must contain at least one uppercase letter (A-Z). Set to true to enforce this requirement.
IdentityPasswordPolicy:RequireNonAlphanumeric: Indicates whether a password must contain at least one non-alphanumeric character (e.g., !, @, #). Set to false to disable this requirement.
IdentityPasswordPolicy:RequiredLength: Specifies the minimum length of a password. Set to 6 to require passwords to be at least 6 characters long.
IdentityPasswordPolicy:RequiredUniqueChars: Specifies the minimum number of unique characters that a password must contain.

API Configuration #

API:EnableRESTv1: Set to true to enable the REST API. See Configure the REST API.
API:ApiOnlyHostname: If set, requests for web pages that arrive with this host name are refused with a message directing the client to the REST API. This allows a separate host name to be dedicated to API traffic.

Explore View Configuration #

Concordance tables show the relationships among variables across time and across studies. Variables can be visually grouped based on how they are organized in your metadata.

Cluster Configuration #

When running more than one instance of Colectica Repository against the same databases, for example behind a load balancer, the instances must share the keys used to protect login cookies. Copy cluster.json.dist to cluster.json on each instance.

{
  "ColecticaCluster": {
    "Enabled": "true",
    "HostId": "host-1",
    "ClusterName": "ColecticaRepositoryProduction",
    "DataProtection": {
      "Provider": "database"
    }
  }
}

ColecticaCluster:Enabled: Set to true to enable cluster mode.
ColecticaCluster:DataProtection:Provider: Set to database to store the data protection keys in the portal database, where every instance can read them.

Sample Database Connection Strings #

The Colectica Repository makes use of two databases per installation, one database to store the metadata content and another that is used by the web portal. You may use whatever name you wish for the databases, by default the documentation refers to them as the colectica and colectica-portal databases.

Ensure that the database account has permissions to create and modify tables and schemas within the database. The database creation is detailed in Create the Repository Database.

SQL Server#

"DefaultConnection": {
  "ConnectionString": "Server=.;Initial Catalog=colectica-portal;Trusted_Connection=True;MultipleActiveResultSets=true;TrustServerCertificate=True",
  "ProviderName": "Microsoft.Data.SqlClient"
},
"ColecticaRepository": {
  "ConnectionString": "Server=.;Initial Catalog=colectica;Integrated Security=SSPI;TrustServerCertificate=True",
  "ProviderName": "Microsoft.Data.SqlClient"
}

Note

Microsoft.Data.SqlClient encrypts connections by default. Either install a trusted certificate on the SQL Server, or add TrustServerCertificate=True to the connection string.

PostgreSQL#

"DefaultConnection": {
  "ConnectionString": "Host=localhost;Database=colectica-portal;Username=postgres;Password=Postgres1234;",
  "ProviderName": "Npgsql"
},
"ColecticaRepository": {
  "ConnectionString": "Host=localhost;Database=colectica;Username=postgres;Password=Postgres1234;",
  "ProviderName": "Npgsql"
}