Configuration¶

Application Configuration¶

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.

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.
Data:DefaultConnection:ConnectionString: The full connection string of the database to use to store authentication tables, when using Colectica Repository’s built in user management.
Data:DefaultConnection:ProviderName: The name of the database provider. Either System.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 System.Data.SqlClient or Npgsql.
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 below for sample database connection strings.

SMTP Configuration¶

SMTP configuration is used for sending notification emails, including password reset emails. 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.
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:ReplyTo: The email address to use as the sender.

Home Page Configuration¶

To show topics on the home page, add the following configuration items.

Home:TopicalConceptSystem:Agency: The agency identifier of the Concept System to display on the home page.
Home:TopicalConceptSystem:Identifier: The unique identifier of the Concept System to display on the home page.

Elasticsearch Configuration¶

Elasticsearch:Host: The hostname and port used to access the Elasticsearch server (e.g., http://localhost:9200). If left blank, Elasticsearch will not be used.
Elasticsearch:IndexName: The prefix of the Elasticsearch index. The index name will be {prefix}_registered_item.

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.
Serilog:Location: The path on disk at which Colectica Repository log files will be stored.
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.

Repository Settings¶

RepositorySettings:Features:EnableSchemaValidation: If true, validation 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 OpenIDConnect or Azure AD to the internal roles store.

RepositorySettings:Http:CspEnable RepositorySettings:Http:CspHeader RepositorySettings:Http:XFrameOptionsEnable RepositorySettings:Http:XFrameOptions RepositorySettings:Http:HttpsRedirectEnable RepositorySettings:Http:HttpRedirectPort RepositorySettings:Http:StrictTransportSecurityEnable RepositorySettings:Http:StrictTransportSecurityMaxAge RepositorySettings:Http:StrictTransportSecurityIncludeSubDomains RepositorySettings:Http:StrictTransportSecurityPreload RepositorySettings:Http:ReferrerPolicyEnabled RepositorySettings:Http:ReferrerPolicy

Miscellaneous Configuration¶

SupportedLanguages: A list of languages supported by the user interface. By default this is "en-US", "fr", "fr-CA". 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.
ForwardedHeadersEnabled: Enable inspection of X-Forwarded-* headers for use behind an HTTP proxy or load balancer.
DefaultAdminUser: If set, the specified user will be granted administrator privileges.
DefaultNewUserRole: If set, the specified role will be added to new user registrations and external logins.
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.

API Configuration¶

API:EnableRESTv1: Set to true to enable the REST API.

Concordance 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.

Concordance:GroupVariablesByPhysicalInstances: Whether to show concordance tables with variables grouped by dataset descriptions.
Concordance:GroupVariablesBySchemes: Whether to show concordance tables with variables grouped by variable sets.

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 the next step.

SQL Server¶

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

PostgreSQL (v5.3.6233 and later)¶

"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"
}

PostgreSQL (Prior to v5.3.6233)¶

Note

The Postgres provider changed User ID to username in a later release.

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