Hyku is primarily configured using environment variables. The default configuration is found in the .env file.
| Name | Description | Default | Development or Test Only |
|---|---|---|---|
| APP_NAME | uniquely identify the endpoint for tenant administration - e.g. https://admin-hyku.example.org (production) or https://admin-hyku.localhost.direct (development) |
hyku | no |
| CHROME_HOSTNAME | specifies the chromium host for feature specs | chrome | yes |
| DB_ADAPTER | which Rails database adapter, mapped in to config/database.yml. Common values are postgresql, mysql2, jdbc, nulldb | postgresql | no |
| DB_HOST | host name for the database | db | no |
| DB_NAME | name of database on database host | hyku | no |
| DB_PASSWORD | password for connecting to database | no | |
| DB_PORT | Port for database connections | 5432 | no |
| DB_TEST_NAME | name of database on database host for tests to run against. Should be different than the development database name or your tests will clobber your dev set up | hyku_test | yes |
| DB_USER | username for the database connection | postgres | no |
| FCREPO_BASE_PATH | Fedora root path | /hykudemo | no |
| FCREPO_DEV_BASE_PATH | Fedora root path used for dev instance | /dev | yes |
| FCREPO_DEVELOPMENT_PORT | Port used for fedora dev instance | 8984 | yes |
| FCREPO_HOST | host name for the fedora repo | fcrepo | no |
| FCREPO_PORT | port for the fedora repo | 8080 | no |
| FCREPO_REST_PATH | Fedora REST endpoint | rest | no |
| FCREPO_STAGING_BASE_PATH | Fedora root path used for dev instance | /staging | no |
| FCREPO_TEST_BASE_PATH | Fedora root path used for test instance | /test | yes |
| FCREPO_TEST_PORT | Test port for the fedora repo 8986 | yes | |
| GOOGLE_ANALYTICS_ID | The Google Analytics account id. Disabled if not set | - | no |
| GOOGLE_ANALYTICS_PROPERTY_ID | The Google Analytics 4 property ID (numeric) | - | no |
| GOOGLE_ACCOUNT_JSON | Google service account JSON credentials | - | no |
| GOOGLE_ACCOUNT_JSON_PATH | Path to Google service account JSON file | - | no |
| HYRAX_ANALYTICS_PROVIDER | Analytics provider: 'ga4', 'google', or 'matomo' | ga4 | no |
| MATOMO_BASE_URL | Matomo instance base URL | - | no |
| MATOMO_SITE_ID | Matomo site ID | - | no |
| MATOMO_AUTH_TOKEN | Matomo API authentication token | - | no |
| GOOGLE_OAUTH_APP_NAME | The name of the application. | - | no |
| GOOGLE_OAUTH_APP_VERSION | The version of application. | - | no |
| GOOGLE_OAUTH_PRIVATE_KEY_SECRET | The secret provided by Google when you created the key. | - | no |
| GOOGLE_OAUTH_PRIVATE_KEY_PATH | The full path to your p12, key file. | - | no |
| GOOGLE_OAUTH_PRIVATE_KEY_VALUE | The value of the p12 file with base64 encryption, only set on deployment as that is how we get the p12 file on the server (see bin/web & bin/worker files) | - | no |
| GOOGLE_OAUTH_CLIENT_EMAIL | OAuth Client email address. | set-me@email.com | no |
| HYKU_ADMIN_HOST | URL of the admin / proprietor host in a multitenant environment | hyku.test | no |
| HYKU_ADMIN_ONLY_TENANT_CREATION | Restrict signing up a new tenant to the admin | false | no |
| HYKU_ALLOW_SIGNUP | Can users register themselves on a given Tenant | true | no |
| HYKU_ASSET_HOST | Host name of the asset server | - | no |
| HYKU_BULKRAX_ENABLED | Is the Bulkrax gem enabled | true | no |
| HYKU_BULKRAX_VALIDATIONS | Unused, pending feature addition by Ubiquity | - | no |
| HYKU_CACHE_API | Use Redis instead of disk for caching | false | no |
| HYKU_CACHE_ROOT | Directory of file cache (if CACHE_API is false) | /app/samvera/file_cache | no |
| HYKU_CONTACT_EMAIL | Email address used for the FROM field when the contact form is submitted | change-me-in-settings@example.com | no |
| HYKU_CONTACT_EMAIL_TO | Email addresses (comma separated) that receive contact form submissions | change-me-in-settings@example.com | no |
| HYKU_DEFAULT_HOST | The host name pattern each tenant will respond to by default. %{tenant} is substituted for the tenants name. | "%{tenant}.#{admin_host}" | no |
| HYKU_DOI_READER | Does the work new / edit form allow reading in a DOI from Datacite? | false | no |
| HYKU_DOI_WRITER | Does saving or updating a work write to Datacite once the work is approved | false | no |
| HYKU_EMAIL_FORMAT | Validate if user emails match a basic email regexp (currently /@\S*.\S*/) |
false | no |
| HYKU_EMAIL_SUBJECT_PREFIX | String to put in front of system email subjects | - | no |
| HYKU_ENABLE_OAI_METADATA | Not used. Placeholder for upcoming OAI feature. | false | no |
| HYKU_FILE_ACL | Set Unix ACLs on file creation. Set to false if using Azure cloud or another network file system that does not allow setting permissions on files. | true | no |
| HYKU_FILE_SIZE_LIMIT | How big a file do you want to accept in the work upload? | 5242880 (5 MB) | no |
| HYKU_GEONAMES_USERNAME | Username used for Geonames connections by the application | '' | no |
| HYKU_GOOGLE_SCHOLARLY_WORK_TYPES | List of work types which should be presented to Google Scholar for indexing. Comma separated WorkType list | - | no |
| HYKU_GTM_ID | If set, enable Google Tag manager with this id. | - | no |
| HYKU_LOCALE_NAME | Not used. Placeholder for upcoming Ubiquity feature | en | no |
| HYKU_MONTHLY_EMAIL_LIST | Not used. Placeholder for upcoming Ubiquity feature | en | no |
| HYKU_MULTITENANT | Set application up for multitenantcy, or use the single tenant version. | false | no |
| HYKU_OAI_ADMIN_EMAIL | OAI endpoint contact address | changeme@example.com | no |
| HYKU_OAI_PREFIX | OAI namespace metadata prefix | oai:hyku | no |
| HYKU_OAI_SAMPLE_IDENTIFIER | OAI example of what an identify might look like | 806bbc5e-8ebe-468c-a188-b7c14fbe34df | no |
| HYKU_ROOT_HOST | What is the very base url that default subdomains should be tacked on to? | hyku.test | no |
| HYKU_S3_BUCKET | If set basic uploads for things like branding images will be sent to S3 | - | no |
| HYKU_SHARED_LOGIN | Not used. Placeholder for upcoming Ubiquity feature | en | no |
| HYKU_SMTP_SETTINGS | String representing a hash of options for tenant specific SMTP defaults. Can be any of from user_name password address domain port authentication enable_starttls_auto |
- | no |
| HYKU_SOLR_COLLECTION_OPTIONS | Overrides of specific collection options for Solr. | {async: nil, auto_add_replicas: nil, collection: { config_name: ENV.fetch('SOLR_CONFIGSET_NAME', 'hyku') }, create_node_set: nil, max_shards_per_node: nil, num_shards: 1, replication_factor: nil, router: { name: nil, field: nil }, rule: nil, shards: nil, snitch: nil} |
no |
| HYKU_SSL_CONFIGURED | Force SSL on page loads and IIIF manifest links | false | no |
| HYKU_WEEKLY_EMAIL_LIST | Not used. Placeholder for upcoming Ubiquity feature | en | no |
| HYKU_YEARLY_EMAIL_LIST | Not used. Placeholder for upcoming Ubiquity feature | en | no |
| HYRAX_ACTIVE_JOB_QUEUE | Which Rails background job runner should be used? | sidekiq | no |
| HYRAX_FITS_PATH | Where is fits.sh installed on the system. Will try the PATH if not set. | /app/fits/fits.sh | no |
| HYRAX_REDIS_NAMESPACE | What namespace should the application use by default | hyrax | no |
| I18N_DEBUG | See [Working with Translations] above | false | yes |
| INITIAL_ADMIN_EMAIL | Admin email used by database seeds. | admin@example.com | no |
| INITIAL_ADMIN_PASSWORD | Admin password used by database seeds. Be sure to change in production. | testing123 | no |
| IN_DOCKER | Used specs to know if we are running inside a container or not. Set to true if in K8S regardless of Docker vs ContainerD | false | yes |
| LD_LIBRARY_PATH | Path used for fits | /app/fits/tools/mediainfo/linux | no |
| NEGATIVE_CAPTCHA_SECRET | A secret value you set for the appliations negative_captcha to work. | default-value-change-me | no |
| RAILS_ENV | https://guides.rubyonrails.org/configuring.html#creating-rails-environments | development | no |
| RAILS_LOG_TO_STDOUT | Redirect all logging to stdout | true | no |
| RAILS_MAX_THREADS | Number of threads to use in puma or sidekiq | 5 | no |
| REDIS_HOST | Host location of redis | redis | no |
| REDIS_PASSWORD | Password for redis, optional | - | no |
| REDIS_URL | Optional explicit redis url, build from host/passsword if not specified | redis://:staging@redis:6397/ | no |
| REPOSITORY_S3_STORAGE | Whether to turn on S3 or S3 like storage for Valkyrie or not | false | no |
| REPOSITORY_S3_BUCKET | If storing file uploads in S3, what bucket should they be put in | - | no |
| REPOSITORY_S3_REGION | Region code for S3 like storage | - | no |
| REPOSITORY_S3_ACCESS_KEY | Access key for S3 like storage | - | no |
| REPOSITORY_S3_SECRET_KEY | The secret key for S3 like storage | - | no |
| REPOSITORY_S3_ENDPOINT | Needed for S3 like storage such as Minio or custom S3 endpoints | - | no |
| REPOSITORY_S3_PORT | Only needed for S3 like storage like Minio | - | no |
| SECRET_KEY_BASE | Used by Rails to secure sessions, should be a 128 character hex | - | no |
| SMTP_ADDRESS | Address of the smtp endpoint for sending email | - | no |
| SMTP_DOMAIN | Domain for sending email | - | no |
| SMTP_PASSWORD | Password for email sending | - | no |
| SMTP_PORT | Port for email sending | - | no |
| SMTP_USER_NAME | Username for the email connection | - | no |
| SOLR_ADMIN_PASSWORD | Solr requires a user/password when accessing the collections API (which we use to create and manage solr collections and aliases) | admin | no |
| SOLR_ADMIN_USER | Solr requires a user/password when accessing the collections API (which we use to create and manage solr collections and aliases) | admin | no |
| SOLR_COLLECTION_NAME | Name of the Solr collection used by non-tenant search. This is required by Hyrax, but is currently unused by Hyku | hydra-development | no |
| SOLR_CONFIGSET_NAME | Name of the Solr configset to use when creating new Solr collections | hyku | no |
| SOLR_HOST | Host for the Solr connection | solr | no |
| SOLR_PORT | Solr port | 8983 | no |
| SOLR_URL | URL for the Solr connection | http://admin:admin@solr:8983/solr/ | no |
| WEB_CONCURRENCY | Number of processes to run in either puma or sidekiq | 2 | no |
Much of the default configuration in Hyku is set up to use multi-tenant mode. This default mode allows Hyku users to run the equivielent of multiple Hyrax installs on a single set of resources. However, sometimes the subdomain splitting multi-headed complexity is simply not needed. If this is the case, then single tenant mode is for you. Single tenant mode will not show the tenant sign up page, or any of the tenant management screens. Instead it shows a single Samvera instance at what ever domain is pointed at the application.
To enable single tenant, set HYKU_MULTITENANT=false in your docker-compose.yml and docker-compose.production.yml configs. After changinig this setting, run rails db:seed to prepopulate the single tenant.
In single tenant mode, both the application root (eg. localhost, or hyku.test) and the tenant url single.* (eg. single.hyku.test) will load the tenant. Override the root host by setting HYKU_ROOT_HOST`.
To change from single- to multi-tenant mode, change the multitenancy/enabled flag to true and restart the application. Change the 'single' tenant account cname in the Accounts edit interface to the correct hostname.
Hyku v6.2 and later includes flexible metadata functionality that allows administrators to configure metadata schemas through the UI using M3 (Machine-readable Metadata Modeling) profiles. This feature is disabled by default and must be explicitly enabled.
- UI-based Configuration: Admins can define and manage metadata fields through the Hyku admin dashboard
- Multi-tenant Support: Full support for Hyku's multi-tenant architecture
- Version Control: Metadata profiles can be versioned, imported, and exported
- Work Type Customization: Control over field labels, required status, searchability, and more per Work Type
- Reduced Developer Dependency: Basic metadata changes no longer require developer involvement
To enable flexible metadata, set the environment variable:
HYRAX_FLEXIBLE=trueAdd this to your .env file for local development, or set it in your deployment environment.
For comprehensive information about flexible metadata, including:
- How to create and manage metadata profiles
- M3 profile structure and syntax
- Work Type configuration
- Schema versioning
- User guide for administrators
See the official Flexible Metadata Documentation on the Samvera Confluence.
For detailed information about configuring controlled vocabularies in Hyku when using flexible metadata, see the Controlled Vocabularies Guide.
For detailed information about configuring analytics in Hyku, see the Analytics Configuration Guide.
You can log all of the I18n lookups to the Rails logger by setting the I18N_DEBUG environment variable to true. This will add a lot of chatter to the Rails logger (but can be very helpful to zero in on what I18n key you should or could use).
$ I18N_DEBUG=true bin/rails serverYou can upload your primary works to S3 in Valkyrie mode by turning on REPOSITORY_S3_STORAGE and setting the accompanying bucket and credentials variables. This enables both AWS S3 and other S3 like storage engines such as Minio. As of this writing this only affects Valkyrie resources and only the primary storage. Derivatives, uploads and branding assets all still go to the shared storage directories.