Installation Guide

Contents:

• Introduction
  • Quick Links
  • Intended Audience
  • Related Guides
  • Getting Help
    • Information to Send to Support When Installation Fails
  • Improving this Guide
• Preparation
  • Choose Your Own Installation Adventure
    • Standard Installation
    • Advanced Installation
  • Architecture and Components
    • Required Components
    • Optional Components
  • System Requirements
    • Hardware Requirements
    • Software Requirements
  • Decisions to Make
  • Next Steps
• Prerequisites
  • Linux
  • Java
    • Installing Java
  • Payara
    • Installing Payara
    • Launching Payara on System Boot
  • PostgreSQL
    • Installing PostgreSQL
    • Configuring Database Access for the Dataverse Installation (and the Dataverse Software Installer)
  • Solr
    • Supported Versions
    • Installing Solr
    • Solr Init Script
    • Securing Solr
  • jq
    • Installing jq
  • ImageMagick
    • Installing and configuring ImageMagick
  • R
    • Installing R
    • Installing the required R libraries
    • Rserve
  • Counter Processor
    • Installing Counter Processor
    • Installing GeoLite Country Database
    • Creating a counter User
    • Installing Counter Processor Python Requirements
  • Next Steps
• Installation
  • Running the Dataverse Software Installer
  • Logging In
    • Superuser Account
  • Troubleshooting
    • Dataset Cannot Be Published
    • Got ERR_ADDRESS_UNREACHABLE While Navigating on Interface or API Calls
    • UnknownHostException While Deploying
  • Fresh Reinstall
    • Drop database
    • Clear Solr
    • Deleting Uploaded Files
    • Rerun Installer
  • Getting Support for Installation Trouble
• Configuration
  • Securing Your Installation
    • Changing the Superuser Password
    • Blocking API Endpoints
    • Forcing HTTPS
    • Recording User IP Addresses
    • Privacy Considerations
      • Email Privacy
    • Additional Recommendations
      • Run Payara as a User Other Than Root
      • Secure Password Storage
      • Enforce Strong Passwords for User Accounts
    • Ongoing Security of Your Installation
    • Reporting Security Issues
  • Network Ports
  • Root Dataverse Collection Permissions
  • Persistent Identifiers and Publishing Datasets
    • Testing PID Providers
    • Configuring PID Providers
      • Global Settings
      • dataverse.pid.providers
      • dataverse.pid.default-provider
      • dataverse.spi.pidproviders.directory
      • Per-Provider Settings
      • dataverse.pid.*.type
      • dataverse.pid.*.label
      • dataverse.pid.*.authority
      • dataverse.pid.*.shoulder
      • dataverse.pid.*.identifier-generation-style
      • dataverse.pid.*.datafile-pid-format
      • dataverse.pid.*.managed-list
      • dataverse.pid.*.excluded-list
      • DataCite-specific Settings
      • dataverse.pid.*.datacite.mds-api-url
      • dataverse.pid.*.datacite.rest-api-url
      • dataverse.pid.*.datacite.username
      • dataverse.pid.*.datacite.password
      • CrossRef-specific Settings
      • dataverse.pid.*.crossref.url
      • dataverse.pid.*.crossref.rest-api-url
      • dataverse.pid.*.crossref.username
      • dataverse.pid.*.crossref.password
      • dataverse.pid.*.crossref.depositor
      • dataverse.pid.*.crossref.depositor-email
      • EZId-specific Settings
      • dataverse.pid.*.ezid.api-url
      • dataverse.pid.*.ezid.username
      • dataverse.pid.*.ezid.password
      • PermaLink-specific Settings
      • dataverse.pid.*.permalink.base-url
      • dataverse.pid.*.permalink.separator
      • Handle-specific Settings
      • dataverse.pid.*.handlenet.index
      • dataverse.pid.*.handlenet.independent-service
      • dataverse.pid.*.handlenet.auth-handle
      • dataverse.pid.*.handlenet.key
      • dataverse.pid.*.handlenet.path
      • dataverse.pid.*.handlenet.passphrase
    • Backward-compatibility for Single PID Provider Installations
      • Configuring Your Dataverse Installation for a Single DOI Provider
      • Configuring Your Dataverse Installation for a Single Handle Provider
      • Configuring Your Dataverse Installation for a Single PermaLink Provider
  • Auth Modes: Local vs. Remote vs. Both
    • Local Only Auth
    • Both Local and Remote Auth
    • Remote Only Auth
  • Bearer Token Authentication
  • SMTP/Email Configuration
  • Database Persistence
    • Basic Database Settings
    • Advanced Database Settings
      • Connection Validation
      • Connection & Statement Leaks
      • Logging & Slow Performance
  • File Storage
    • Multi-store Basics
    • Labels for File Stores
    • File Storage
    • Swift Storage
      • Setting up Compute with Swift
    • Amazon S3 Storage (or Compatible)
      • First: Set Up Accounts and Access Credentials
        • Preparation When Using Amazon’s S3 Service
        • Preparation When Using Custom S3-Compatible Service
        • Manually Set Up Credentials File
        • Console Commands to Set Up Access Configuration
      • Second: Configure Your Dataverse Installation to use S3 Storage
        • S3 Tagging
        • Finalizing S3 Configuration
        • List of S3 Storage Options
        • Credentials via MicroProfile Config
        • Reported Working S3-Compatible Storage
        • Migrating from Local Storage to S3
    • Trusted Remote Storage
    • Globus Storage
    • Temporary Upload File Storage
  • Rate Limiting
  • Branding Your Installation
    • Parts of a Dataverse Installation Webpage
    • Installation Name/Brand Name
    • Header Block
      • Navbar
        • Custom Navbar Logo
        • About URL
        • User Guide URL
        • Support URL
        • Sign Up
      • Custom Header
    • Content Block
      • Custom Homepage
    • Footer Block
      • Default Footer
        • Footer Copyright
      • Custom Footer
    • Custom Stylesheet
  • Internationalization
    • Adding Multiple Languages to the Dropdown in the Header
    • Allowing the Language Used for Dataset Metadata to be Specified
    • Configuring the “lang” Directory
    • Creating a languages.zip File
    • Load the languages.zip file into your Dataverse Installation
    • How to Help Translate the Dataverse Software Into Your Language
    • Tools for Translators
  • Web Analytics Code
    • Tracking Button Clicks
  • Configuring Licenses
    • Setting the Default License
    • Adding Licenses
      • Adding Creative Common Licenses
      • Adding Software Licenses
      • Contributing to the Collection of Standard Licenses Above
      • Adding Custom Licenses
    • Removing Licenses
    • Disabling Custom Dataset Terms
  • Sorting licenses
  • BagIt File Handler
  • BagIt Export
    • Duracloud Configuration
    • Local Path Configuration
    • Google Cloud Configuration
    • S3 Configuration
    • BagIt Export API Calls
    • PostPublication Workflow
    • Configuring bag-info.txt
  • Going Live: Launching Your Production Deployment
    • Letting Search Engines Crawl Your Installation
      • Ensure robots.txt Is Not Blocking Search Engines
      • Creating a Sitemap and Submitting it to Search Engines
        • Creating a Sitemap
        • Single Sitemap File
        • Multiple Sitemap Files (Sitemap Index File)
        • Submitting Your Sitemap to Search Engines
    • Putting Your Dataverse Installation on the Map at dataverse.org
    • Administration of Your Dataverse Installation
    • Setting Up Integrations
  • JVM Options
    • dataverse.fqdn
    • dataverse.siteUrl
    • dataverse.files.directory
    • dataverse.files.uploads
    • dataverse.files.docroot
    • dataverse.auth.password-reset-timeout-in-minutes
    • dataverse.db.name
    • dataverse.db.user
    • dataverse.db.password
    • dataverse.db.host
    • dataverse.db.port
    • dataverse.db.parameters
    • dataverse.solr.host
    • dataverse.solr.port
    • dataverse.solr.core
    • dataverse.solr.protocol
    • dataverse.solr.path
    • dataverse.solr.concurrency.max-async-indexes
    • dataverse.rserve.host
    • dataverse.rserve.port
    • dataverse.rserve.user
    • dataverse.rserve.password
    • dataverse.rserve.tempdir
    • dataverse.dropbox.key
    • dataverse.path.imagemagick.convert
    • dataverse.dataAccess.thumbnail.image.limit
    • dataverse.dataAccess.thumbnail.pdf.limit
    • Legacy Single PID Provider: dataverse.pid.datacite.mds-api-url
    • Legacy Single PID Provider: dataverse.pid.datacite.rest-api-url
    • Legacy Single PID Provider: dataverse.pid.datacite.username
    • Legacy Single PID Provider: dataverse.pid.datacite.password
    • Legacy Single PID Provider: dataverse.pid.handlenet.key.path
    • Legacy Single PID Provider: dataverse.pid.handlenet.key.passphrase
    • Legacy Single PID Provider: dataverse.pid.handlenet.index
    • Legacy Single PID Provider: dataverse.pid.permalink.base-url
    • Legacy Single PID Provider: dataverse.pid.ezid.api-url
    • Legacy Single PID Provider: dataverse.pid.ezid.username
    • Legacy Single PID Provider: dataverse.pid.ezid.password
    • dataverse.timerServer
    • dataverse.lang.directory
    • dataverse.files.hide-schema-dot-org-download-urls
    • dataverse.useripaddresssourceheader
    • dataverse.personOrOrg.assumeCommaInPersonName
    • dataverse.personOrOrg.orgPhraseArray
    • dataverse.api.signature-secret
    • dataverse.api.allow-incomplete-metadata
    • dataverse.ui.show-validity-label-when-published
    • dataverse.signposting.level1-author-limit
    • dataverse.signposting.level1-item-limit
    • dataverse.mail.system-email
    • dataverse.mail.support-email
    • dataverse.mail.cc-support-on-contact-email
    • dataverse.mail.debug
    • dataverse.mail.mta.*
    • dataverse.ui.allow-review-for-incomplete
    • dataverse.ui.show-validity-filter
    • dataverse.spi.exporters.directory
    • dataverse.netcdf.geo-extract-s3-direct-upload
    • dataverse.storageuse.disable-storageuse-increments
    • dataverse.auth.oidc.*
    • dataverse.files.guestbook-at-request
    • dataverse.bagit.sourceorg.name
    • dataverse.bagit.sourceorg.address
    • dataverse.bagit.sourceorg.email
    • dataverse.files.globus-monitoring-server
  • Feature Flags
  • Application Server Settings
    • http.request-timeout-seconds
    • mp.config.profile
  • Database Settings
    • :BlockedApiPolicy
    • :BlockedApiEndpoints
    • :BlockedApiKey
    • BuiltinUsers.KEY
    • :SearchApiRequiresToken
    • :SystemEmail
    • :HomePageCustomizationFile
    • :LogoCustomizationFile
    • :HeaderCustomizationFile
    • :DisableRootDataverseTheme
    • :FooterCustomizationFile
    • :StyleCustomizationFile
    • :WebAnalyticsCode
    • :FooterCopyright
    • Legacy Single PID Provider: :DoiProvider
    • Legacy Single PID Provider: :Protocol
    • Legacy Single PID Provider: :Authority
    • Legacy Single PID Provider: :Shoulder
    • Legacy Single PID Provider: :IdentifierGenerationStyle
    • Legacy Single PID Provider: :DataFilePIDFormat
    • :FilePIDsEnabled
    • :AllowEnablingFilePIDsPerCollection
    • Legacy Single PID Provider: :IndependentHandleService
    • Legacy Single PID Provider: :HandleAuthHandle
    • :FileValidationOnPublishEnabled
    • :ApplicationTermsOfUse
    • :ApplicationPrivacyPolicyUrl
    • :ApiTermsOfUse
    • :ExcludeEmailFromExport
    • :NavbarAboutUrl
    • :NavbarGuidesUrl
    • :GuidesBaseUrl
    • :GuidesVersion
    • :NavbarSupportUrl
    • :MetricsUrl
    • :MaxFileUploadSizeInBytes
    • :MultipleUploadFilesLimit
    • :ZipDownloadLimit
    • :TabularIngestSizeLimit
    • :ZipUploadFilesLimit
    • :SolrHostColonPort
    • :SolrFullTextIndexing
    • :SolrMaxFileSizeForFullTextIndexing
    • :DisableSolrFacets
    • :DisableSolrFacetsForGuestUsers
    • :DisableSolrFacetsWithoutJsession
    • :DisableUncheckedTypesFacet
    • :SignUpUrl
    • :LoginSessionTimeout
    • :DatasetPublishPopupCustomText
    • :DatasetPublishPopupCustomTextOnAllVersions
    • :SearchHighlightFragmentSize
    • :ScrubMigrationData
    • :MinutesUntilConfirmEmailTokenExpires
    • :DefaultAuthProvider
    • :AllowSignUp
    • :AllowRemoteAuthSignUp
    • :FileFixityChecksumAlgorithm
    • :PVMinLength
    • :PVMaxLength
    • :PVNumberOfConsecutiveDigitsAllowed
    • :PVCharacterRules
    • :PVNumberOfCharacteristics
    • :PVDictionaries
    • :PVGoodStrength
    • :PVCustomPasswordResetAlertMessage
    • :ShibPassiveLoginEnabled
    • :ShibAffiliationAttribute
    • :ShibAttributeCharacterSetConversionEnabled
    • :ShibAffiliationOrder
    • :ShibAffiliationSeparator
    • :ComputeBaseUrl
    • :CloudEnvironmentName
    • :PublicInstall
    • :UploadMethods
    • :GuestbookResponsesPageDisplayLimit
    • :CustomDatasetSummaryFields
    • :AllowApiTokenLookupViaApi
    • :ProvCollectionEnabled
    • :MetricsCacheTimeoutMinutes
    • :MDCLogPath
    • :DisplayMDCMetrics
    • :MDCStartDate
    • :Languages
    • :MetadataLanguages
    • :InheritParentRoleAssignments
    • :AllowCors
    • :ChronologicalDateFacets
    • :CustomZipDownloadServiceUrl
    • :CreateDataFilesMaxErrorsToDisplay
    • :BagItHandlerEnabled
    • :BagValidatorJobPoolSize
    • :BagValidatorMaxErrors
    • :BagValidatorJobWaitInterval
    • :ArchiverClassName
    • :ArchiverSettings
    • :BagGeneratorThreads
    • :DuraCloudHost
    • :DuraCloudPort
    • :DuraCloudContext
    • :BagItLocalPath
    • :GoogleCloudBucket
    • :GoogleCloudProject
    • :S3ArchiverConfig
    • :InstallationName
    • :ExportInstallationAsDistributorOnlyWhenNotSet
    • :AnonymizedFieldTypeNames
    • :DatasetChecksumValidationSizeLimit
    • :DataFileChecksumValidationSizeLimit
    • :SendNotificationOnDatasetCreation
    • :CVocConf
    • :ControlledVocabularyCustomJavaScript
    • :AllowedCurationLabels
    • :AllowCustomTermsOfUse
    • :MaxEmbargoDurationInMonths
    • :MinRetentionDurationInMonths
    • :DataverseMetadataValidatorScript
    • :DataverseMetadataPublishValidationFailureMsg
    • :DataverseMetadataUpdateValidationFailureMsg
    • :DatasetMetadataValidatorScript
    • :DatasetMetadataValidationFailureMsg
    • :ExternalValidationAdminOverride
    • :FileCategories
    • :ShowMuteOptions
    • :AlwaysMuted
    • :NeverMuted
    • :LDNMessageHosts
    • :LDN_TARGET
    • :LDNAnnounceRequiredFields
    • :GlobusAppUrl
    • :GlobusPollingInterval
    • :GlobusSingleFileTransfer
    • :WebloaderUrl
    • :CategoryOrder
    • :OrderByFolder
    • :AllowUserManagementOfOrder
    • :UseStorageQuotas
    • :StoreIngestedTabularFilesWithVarHeaders
    • :RateLimitingDefaultCapacityTiers
    • :RateLimitingCapacityByTierAndAction
• Upgrading
• Shibboleth
  • Introduction
  • Installation
    • System Requirements
    • Install Apache
    • Install Shibboleth
      • Install Shibboleth Yum Repo
      • Install Shibboleth Via Yum
  • Configure Payara
    • App Server HTTP and HTTPS ports
    • AJP
    • SSLEngine Warning Workaround
  • Configure Apache
    • Enforce HTTPS
    • Edit Apache ssl.conf File
  • Configure Shibboleth
    • shibboleth2.xml
      • Specific Identity Provider(s)
      • Identity Federation
    • Shibboleth Attributes
    • attribute-map.xml
    • Shibboleth and ADFS
  • Disable or Reconfigure SELinux
    • Disable SELinux
    • Reconfigure SELinux to Accommodate Shibboleth
      • Put Type Enforcement (TE) File in misc directory
      • Navigate to misc directory
      • Run checkmodule
      • Run semodule_package
      • Run semodule
  • Restart Apache and Shibboleth
  • Configure Apache and shibd to Start at Boot
  • Verify DiscoFeed and Metadata URLs
  • Add the Shibboleth Authentication Provider to Your Dataverse Installation
  • Exchange Metadata with Your Identity Provider
  • Backup sp-cert.pem and sp-key.pem Files
  • Debugging
  • Converting Accounts
    • Converting Local Users to Shibboleth
    • Converting Shibboleth Users to Local
  • Institution-Wide Shibboleth Groups
  • Multi-Factor Authentication
• OAuth Login Options
  • Introduction
  • Setup
    • Identity Provider Side
      • Obtain Client ID and Client Secret
    • Dataverse Installation Side
      • ORCID Sandbox
    • Disabling Sign Up
  • Converting Local Users to OAuth
  • Converting OAuth Users to Local
• OpenID Connect Login Options
  • Introduction
  • Other Use Cases and Combinations
  • How to Use
    • Enabling PKCE Security
  • Provision a Provider
    • Provision via REST API
    • Provision via JVM Options
• External Tools
  • Inventory of External Tools
  • Managing External Tools
  • Building External Tools
• Advanced Installation
  • Multiple App Servers
    • Detecting Which App Server a User Is On
  • Licensing
    • Standardizing Custom Licenses
  • Optional Components
    • Standalone “Zipper” Service Tool
    • External Metadata Exporters
      • Enabling External Exporters
      • Inventory of External Exporters
      • Developing New Exporters