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 theappsettings.json.dist
file toappsettings.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
orNpgsql
.- 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
orNpgsql
.- UseWindowsAuthentication
Set to
true
if using Windows authentication; otherwise set tofalse
. Settingtrue
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:EnableSsl
Set to
true
to enable SSL.- 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.
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 can be used for the web portal’s search page.
- Elasticsearch:Enabled
Set to
true
to enable Elasticsearch for the the portal search page. Set tofalse
to use the built-in database search.- 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
.- Elasticsearch:EnableApiVersioningHeader
Set to
true
to enable the API versioning header in Elasticsearch requests. This allows using newer versions of the Elasticsearch API.
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¶
Features¶
- 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.
HTTP¶
- Features:Http:CspEnable
Indicates whether Content Security Policy (CSP) is enabled. Set to
true
to enable CSP.- Features:Http:CspHeader
Specifies the Content Security Policy header value. Example:
default-src 'self'; script-src 'self' 'unsafe-eval'; style-src 'self' 'unsafe-inline'; img-src 'self' data: https:; object-src 'none'
.- Features:Http:XFrameOptionsEnable
Indicates whether the X-Frame-Options header is enabled. Set to
true
to enable the X-Frame-Options header.- Features:Http:XFrameOptions
Specifies the value for the X-Frame-Options header. Example:
SAMEORIGIN
.- Features:Http:XContentTypeOptionsEnable
Indicates whether the X-Content-Type-Options header is enabled. Set to
true
to enable the X-Content-Type-Options header.- Features:Http:HttpsRedirectEnable
Indicates whether HTTP requests should be redirected to HTTPS. Set to
true
to enable HTTPS redirection.- Features:Http:HttpsRedirectPort
Specifies the port to which HTTP requests should be redirected. Set to
443
for standard HTTPS redirection.- Features:Http:StrictTransportSecurityEnable
Indicates whether HTTP Strict Transport Security (HSTS) is enabled. Set to
true
to enable HSTS.- Features:Http:StrictTransportSecurityMaxAge
Specifies the max-age directive for HSTS in seconds. Set to
31536000
(1 year) to enforce HSTS for one year.- Features:Http:StrictTransportSecurityIncludeSubDomains
Indicates whether the HSTS policy applies to subdomains. Set to
true
to include subdomains in the HSTS policy.- Features:Http:StrictTransportSecurityIncludePreload
Indicates whether the HSTS policy includes the preload directive. Set to
false
to exclude the preload directive.- Features:Http:ReferrerPolicyEnabled
Indicates whether the Referrer-Policy header is enabled. Set to
true
to enable the Referrer-Policy header.- Features:Http:ReferrerPolicy
Specifies the value for the Referrer-Policy header. Example:
strict-origin-when-cross-origin
.- Features:Http:SetHostCookiePrefix
Indicates whether to set the host cookie prefix. Set to
false
to disable the host cookie prefix.
Portal¶
- Features: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.- Features: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.- Features:Portal:DisableSwaggerUI
Indicates whether the Swagger documentation for the included REST API should be disabled. Set to
false
to enable the Swagger UI.- Features:Portal:CollapseQuestionResponseDomainsInFlowchart
Indicates whether question response domains should be collapsed in the flowchart. Set to
false
to keep the response domains expanded.- Features:Portal:QuestionGridDisplayStyle
Specifies the display style for the question grid. Possible values are
Linear
andNonLinear
. Set toLinear
to display simple lists of dimensions and measures. Set toNonLinear
to display the question grid in a table.- Features: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.
HealthChecks¶
- Features:HealthChecks:MinimumFreeDiskCacheMegabytes
Specifies the minimum amount of free disk space (in megabytes) required for the cache. Set to
500
to require at least 500 MB of free disk space for the cache.- Features:HealthChecks:MinimumFreeDiskLogMegabytes
Specifies the minimum amount of free disk space (in megabytes) required for logs. Set to
250
to require at least 250 MB of free disk space for logs.
General¶
- Features:RepositorySecurityMode
Specifies the security mode for the repository. Possible values are
Disabled
,Permissive
, andEnforcing
. Set toNone
to disable security features. Set toPermissive
to allow any user to perform operations that are normally restricted to certain roles. Set toEnforcing
to enable normal security features.- Features:CommandTimeoutInSeconds
Specifies the timeout for database commands in seconds. Set to
30
to allow commands to run for up to 30 seconds.
Workflow Configuration¶
Colectica Repository can be configured to connect to Colectica Workflow Services.
- 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 with a workflow preview feature that allows users to preview the results of workflow replications before approving them.
- 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¶
- 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
andWebDAV
.- FileStorage:MaxUploadSize
Specifies the maximum upload size in bytes. Set to
104857601
to allow uploads up to approximately 100 MB.- 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. Set to the appropriate username for authentication.
- FileStorage:WebDAV:Password
Specifies the password for accessing the WebDAV storage. Set to the appropriate password for authentication.
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.
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.
- XForwardedForDisabled
Disable inspection of the X-Forwarded-For header.
- 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.
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.
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.
See also
See Data Concordance for more information on concordance views.
By default, the concordance tables in the Explore views are constructed for items under a single Series.
When a single series is appropriate, no additional configuration is required.
To enable concordance tables to be constructed for multiple series, the order of the series must be specified
in the appsettings.json
file.
The ordered list of series is specified for each Concept Set.
A sample configuration looks like this:
"Explore": {
"Views": [
{
"ConceptSchemeAgency": "int.example",
"ConceptSchemeId": "8a3e03ac-4ff3-4043-b997-96847e0c86fb",
"GroupIdentifiers": [
{
"Agency": "int.example",
"Id": "fab89d2e-030e-4a22-b67c-1e0762577d58"
},
{
"Agency": "int.example",
"Id": "502aac29-f6db-4b64-a6d2-92b72f7f8e4d"
},
{
"Agency": "int.example",
"Id": "9b2cd493-073a-4128-8b5b-530a3eb67481"
}
]
}
]
}
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"
}