From 585f11d3e108c226741b7173bf035615a5c42a92 Mon Sep 17 00:00:00 2001 From: Philip Durbin Date: Thu, 28 Jan 2016 10:08:13 -0500 Subject: [PATCH] Installation Guide: many improvements #2884 - enumerated all (?) config options #2283 #2661 --- .../source/installation/administration.rst | 50 ++- .../source/installation/config.rst | 380 +++++++++++++++--- .../source/installation/installation-main.rst | 49 ++- .../source/installation/intro.rst | 2 - .../source/installation/prep.rst | 4 +- 5 files changed, 399 insertions(+), 86 deletions(-) diff --git a/doc/sphinx-guides/source/installation/administration.rst b/doc/sphinx-guides/source/installation/administration.rst index eb7f0428432..9a5a72a6ee5 100644 --- a/doc/sphinx-guides/source/installation/administration.rst +++ b/doc/sphinx-guides/source/installation/administration.rst @@ -1,13 +1,59 @@ Administration ============== +This section focuses on system and database administration tasks. Please see the :doc:`/user/index` for tasks having to do with having the "Admin" role on a dataverse or dataset. + .. contents:: :local: +Solr Search Index +----------------- + +Dataverse requires Solr to be operational at all times. If you stop Solr, you should see a error about this on the home page, which is powered by the search index Solr provides. You set up Solr by following the steps in the :doc:`prerequisites` section and the :doc:`config` section explained how to configure it. This section is about the care and feeding of the search index. PostgreSQL is the "source of truth" and the Dataverse application will copy data from PostgreSQL into Solr. For this reason, the search index can be rebuilt at any time but depending on the amount of data you have, this can be a slow process. You are encouraged to experiment with production data to get a sense of how long a full reindexing will take. + +Full Reindex +++++++++++++ + +There are two ways to perform a full reindex of the Dataverse search index. Starting with a "clear" ensures a completely clean index but involves downtime. Reindexing in place doesn't involve downtime but does not ensure a completely clean index. + +Clear and Reindex +~~~~~~~~~~~~~~~~~ + +Clearing Data from Solr +....................... + +Please note that the moment you issue this command, it will appear to end users looking at the home page that all data is gone! This is because the home page is powered by the search index. + +``curl http://localhost:8080/api/admin/index/clear`` + +Start Async Reindex +................... + +Please note that this operation may take hours depending on the amount of data in your system. This known issue is being tracked at https://github.com/IQSS/dataverse/issues/50 + +``curl http://localhost:8080/api/admin/index`` + +Reindex in Place +~~~~~~~~~~~~~~~~ + +An alternative to completely clearing the search index is to reindex in place. + +Clear Index Timestamps +...................... + +``curl -X DELETE http://localhost:8080/api/admin/index/timestamps`` + +Start or Continue Async Reindex +................................ + +If indexing stops, this command should pick up where it left off based on which index timestamps have been set, which is why we start by clearing these timestamps above. These timestamps are stored in the ``dvobject`` database table. + +``curl http://localhost:8080/api/admin/index/continue`` + User Administration ------------------- -Deleting an API token -~~~~~~~~~~~~~~~~~~~~~ +Deleting an API Token ++++++++++++++++++++++ If an API token is compromised it should be deleted. Users can generate a new one for themselves, but someone with access to the database can delete tokens as well. diff --git a/doc/sphinx-guides/source/installation/config.rst b/doc/sphinx-guides/source/installation/config.rst index f63592a8745..157aefade4e 100644 --- a/doc/sphinx-guides/source/installation/config.rst +++ b/doc/sphinx-guides/source/installation/config.rst @@ -2,57 +2,290 @@ Configuration ============= -Some of the configuration of Dataverse was performed by the installer script described in the :doc:`installation-main` section, but Dataverse settings can be further tweaked via settings in the database, JVM options, and configuration files. +Now that you've successfully logged into Dataverse with a superuser account after going through a basic :doc:`installation-main`, you'll need to secure and configure your installation. + +Settings within Dataverse itself are managed via JVM options or by manipulating values in the ``setting`` table directly or through API calls. Configuring Solr requires manipulating XML files. + +Once you have finished securing and configuring your Dataverse installation, proceed to the :doc:`administration` section. Advanced configuration topics are covered in the :doc:`r-rapache-tworavens` and :doc:`shibboleth` sections. .. contents:: :local: +Securing Your Installation +-------------------------- + +Blocking API Endpoints +++++++++++++++++++++++ + +The :doc:`/api/native-api` contains a useful but potentially dangerous API endpoint called "admin" that allows you to change system settings, make ordinary users into superusers, and more. In addition, there is a "test" API used for development and troubleshooting. By default, both of these APIs can be operated on remotely and without the need for any authentication. https://github.com/IQSS/dataverse/issues/1886 was opened to explore changing these defaults, but until then it is very important to block both the "admin" and "test" endpoint with a script called ``post-install-api-block.sh`` available from https://github.com/IQSS/dataverse/blob/develop/scripts/api/post-install-api-block.sh . See also the section on ``:BlockedApiPolicy`` below. + +Forcing HTTPS ++++++++++++++ + +To avoid having your users send credentials in the clear, it's strongly recommended to force all web traffic to go through HTTPS (port 443) rather than HTTP (port 80). The ease with which one can install a valid SSL cert into Apache compared with the same operation in Glassfish might be a compelling enough reason to front Glassfish with Apache. In addition, Apache can be configured to rewrite HTTP to HTTPS with rules such as those found at https://wiki.apache.org/httpd/RewriteHTTPToHTTPS or in the section on :doc:`shibboleth`. + +Solr +---- + +schema.xml +++++++++++ + +The :doc:`prerequisites` section explained that Dataverse requires a specific Solr schema file called ``schema.xml`` that can be found in the Dataverse distribution. You should have already replaced the default ``example/solr/collection1/conf/schema.xml`` file that ships with Solr. + +jetty.xml ++++++++++ + +Stop Solr and edit ``solr-4.6.0/example/etc/jetty.xml`` to have the following value: ``102400``. Without this higher value in place, it will appear that no data has been added to your dataverse installation and ``WARN org.eclipse.jetty.http.HttpParser – HttpParser Full for /127.0.0.1:8983`` will appear in the Solr log. See also https://support.lucidworks.com/hc/en-us/articles/201424796-Error-when-submitting-large-query-strings- + +Network Ports +------------- + +The need to redirect port HTTP (port 80) to HTTPS (port 443) for security has already been mentioned above and the fact that Glassfish puts these services on 8080 and 8181, respectively, was touched on in the :doc:`installation-main` section. You have a few options that basically boil down to if you want to introduce Apache into the mix or not. If you need :doc:`shibboleth` support you need Apache and you should proceed directly to that doc for guidance on fronting Glassfish with Apache. + +If you don't want to front Glassfish with a proxy such as Apache or nginx, you will need to configure Glassfish to run HTTPS on 443 like this: + +``asadmin set server-config.network-config.network-listeners.network-listener.http-listener-2.port=443`` + +Most likely you'll want to put a valid cert into Glassfish, which is certainly possible but out of scope for this guide. + +What about port 80? Even if you don't front Dataverse with Apache, you may want to let Apache run on port 80 just to rewrite HTTP to HTTPS as described above. You can use a similar command as above to change the HTTP port that Glassfish uses from 8080 to 80 (substitute ``http-listener-1.port=80``). Glassfish can be used to enforce HTTPS on its own without Apache, but configuring this is an exercise for the reader. Answers here may be helpful: http://stackoverflow.com/questions/25122025/glassfish-v4-java-7-port-unification-error-not-able-to-redirect-http-to + +Root Dataverse Configuration +---------------------------- + +The user who creates a dataverse is given the "Admin" role on that dataverse. The root dataverse is created automatically for you by the installer and the "Admin" is the superuser account ("dataverseAdmin") we used in the :doc:`installation-main` section to confirm that we can log in. These next steps of configuring the root dataverse require the "Admin" role on the root dataverse, but not the much more powerful superuser attribute. In short, users with the "Admin" role are subject to the permission system. A superuser, on the other hand, completely bypasses the permission system. You can give non-superusers the "Admin" role on the root dataverse if you'd like them to configure the root dataverse. + +Root Dataverse Permissions +++++++++++++++++++++++++++ + +In order for non-superusers to start creating dataverses or datasets, you need click "Edit" then "Permissions" and make choices about which users can add dataverses or datasets within the root dataverse. (There is an API endpoint for this operation as well.) Again, the user who creates a dataverse will be granted the "Admin" role on that dataverse. + +Publishing the Root Dataverse ++++++++++++++++++++++++++++++ + +Non-superusers who are not "Admin" on the root dataverse will not be able to to do anything useful until the root dataverse has been published. + +Customizing the Root Dataverse +++++++++++++++++++++++++++++++ + +As the person installing Dataverse you may or may not be local metadata expert. You may want to have others sign up for accounts and grant them the "Admin" role at the root dataverse to configure metadata fields, browse/search facets, templates, guestbooks, etc. For more on these topics, consult the :doc:`/user/dataverse-management` section of the User Guide. + +Once this configuration is complete, your Dataverse installation should be ready for users to start playing with it. That said, there are many more configuration options available, which will be explained below. + +JVM Options +----------- + +JVM stands Java Virtual Machine and as a Java application, Glassfish can read JVM options when it is started. A number of JVM options are configured by the installer below is a complete list of the Dataverse-specific JVM options. You can inspect the configured options by running ``asadmin list-jvm-options | egrep 'dataverse|doi' +``. + +When changing values these values with ``asadmin``, you'll need to delete the old value before adding a new one, like this: + +``asadmin delete-jvm-options "-Ddataverse.fqdn=old.example.com"`` + +``asadmin create-jvm-options "-Ddataverse.fqdn=dataverse.example.com"`` + +It's also possible to change these values by stopping Glassfish, editing ``glassfish4/glassfish/domains/domain1/config/domain.xml``, and restarting Glassfish. + +dataverse.fqdn +++++++++++++++ + +If the Dataverse server has multiple DNS names, this option specifies the one to be used as the "official" host name. For example, you may want to have dataverse.foobar.edu, and not the less appealling server-123.socsci.foobar.edu to appear exclusively in all the registered global identifiers, Data Deposit API records, etc. + +The password reset feature requires ``dataverse.fqdn`` to be configured. + +| Do note that whenever the system needs to form a service URL, by default, it will be formed with ``https://`` and port 443. I.e., +| ``https://{dataverse.fqdn}/`` +| If that does not suit your setup, you can define an additional option, ``dataverse.siteUrl``, explained below. + +dataverse.siteUrl ++++++++++++++++++ + +| and specify the alternative protocol and port number. +| For example, configured in domain.xml: +| ``-Ddataverse.fqdn=dataverse.foobar.edu`` +| ``-Ddataverse.siteUrl=http://${dataverse.fqdn}:8080`` + +dataverse.files.directory ++++++++++++++++++++++++++ + +This is how you configure the path to which files uploaded by users are stored. The installer prompted you for this value. + +dataverse.auth.password-reset-timeout-in-minutes +++++++++++++++++++++++++++++++++++++++++++++++++ + +Users have 60 minutes to change their passwords by default. You can adjust this value here. + +dataverse.rserve.host ++++++++++++++++++++++ + +Configuration for :doc:`r-rapache-tworavens`. + +dataverse.rserve.port ++++++++++++++++++++++ + +Configuration for :doc:`r-rapache-tworavens`. + +dataverse.rserve.user ++++++++++++++++++++++ + +Configuration for :doc:`r-rapache-tworavens`. + +dataverse.rserve.tempdir +++++++++++++++++++++++++ +Configuration for :doc:`r-rapache-tworavens`. + +dataverse.rserve.password ++++++++++++++++++++++++++ + +Configuration for :doc:`r-rapache-tworavens`. + +dataverse.dropbox.key ++++++++++++++++++++++ + +Dropbox integration is optional. Enter your key here. + +dataverse.path.imagemagick.convert +++++++++++++++++++++++++++++++++++ + +For overriding the default path to the ``convert`` binary from ImageMagick (``/usr/bin/convert``). + +dataverse.dataAccess.thumbnail.image.limit +++++++++++++++++++++++++++++++++++++++++++ + +For limiting the size of thumbnail images generated from files. + +dataverse.dataAccess.thumbnail.pdf.limit +++++++++++++++++++++++++++++++++++++++++ + +For limiting the size of thumbnail images generated from files. + +doi.baseurlstring ++++++++++++++++++ + +As of this writing "https://ezid.cdlib.org" is the only valid value. See also these related database settings below: + +- :DoiProvider +- :Protocol +- :Authority +- :DoiSeparator + +doi.username +++++++++++++ + +Used in conjuction with ``doi.baseurlstring``. + +doi.password +++++++++++++ + +Used in conjuction with ``doi.baseurlstring``. + +dataverse.handlenet.admcredfile ++++++++++++++++++++++++++++++++ + +For Handle support (not fully developed). + +dataverse.handlenet.admprivphrase ++++++++++++++++++++++++++++++++++ +For Handle support (not fully developed). + Database Settings +----------------- + +These settings are stored in the ``setting`` table but can be read and modified via the "admin" endpoint of the :doc:`/api/native-api` for easy scripting. + +The most commonly used configuration options are listed first. + +:BlockedApiPolicy +++++++++++++++++ -These settings are stored in the ``setting`` table but are available via the "admin" API for easy scripting. +Out of the box, all API endpoints are completely open as mentioned in the section on security above. It is highly recommend that you choose one of the policies below and also configure ``:BlockedApiEndpoints``. -:ApplicationPrivacyPolicyUrl ----------------------------- +- localhost-only: Allow from localhost. +- unblock-key: Require a key defined in ``:BlockedApiKey``. +- drop: Disallow the blocked endpoints completely. -Specify a URL where users can read your Privacy Policy, linked from the bottom of the page. +``curl -X PUT -d localhost-only http://localhost:8080/api/admin/settings/:BlockedApiEndpoints`` -``curl -X PUT -d http://best-practices.dataverse.org/harvard-policies/harvard-privacy-policy.html http://localhost:8080/api/admin/settings/:ApplicationPrivacyPolicyUrl`` +:BlockedApiEndpoints +++++++++++++++++++++ + +A comma separated list of API endpoints to be blocked. For a production installation, "admin" and "test" should be blocked, as mentioned in the section on security above. + +``curl -X PUT -d "admin,test" http://localhost:8080/api/admin/settings/:BlockedApiEndpoints`` + +:BlockedApiKey +++++++++++++++ + +Used in conjunction with the ``:BlockedApiPolicy`` being set to ``unblock-key``. When calling blocked APIs, add a query parameter of ``unblock-key=theKeyYouChose`` to use the key. + +``curl -X PUT -d s3kretKey http://localhost:8080/api/admin/settings/:BlockedApiKey`` + +:DoiProvider +++++++++++++ + +As of this writing "EZID" is the only valid options. DataCite support is planned: https://github.com/IQSS/dataverse/issues/24 + +``curl -X PUT -d EZID http://localhost:8080/api/admin/settings/:DoiProvider`` + +:Protocol ++++++++++ + +As of this writing "doi" is the only valid option for the protocol for a persistent ID. + +``curl -X PUT -d doi http://localhost:8080/api/admin/settings/:Protocol`` + +:Authority +++++++++++ + +Use the DOI authority assigned to you by EZID. + +``curl -X PUT -d 10.xxxx http://localhost:8080/api/admin/settings/:Authority`` + +:DoiSeparator ++++++++++++++ + +It is recommended that you keep this as a slash ("/"). + +``curl -X PUT -d "/" http://localhost:8080/api/admin/settings/:DoiSeparator`` :ApplicationTermsOfUse ----------------------- +++++++++++++++++++++++ -Upload a text file containing the Terms of Use to be displayed at sign up. +Upload an HTML file containing the Terms of Use to be displayed at sign up. Supported HTML tags are listed under the :doc:`/user/dataset-management` section of the User Guide. ``curl -X PUT -d@/tmp/apptou.html http://localhost:8080/api/admin/settings/:ApplicationTermsOfUse`` -:ApiTermsOfUse --------------- +Unfortunately, in most cases, the text file will probably be too big to upload (>1024 characters) due to a bug. A workaround has been posted to https://github.com/IQSS/dataverse/issues/2669 -Upload a text file containing the API Terms of Use. +:ApplicationPrivacyPolicyUrl +++++++++++++++++++++++++++++ -``curl -X PUT -d@/tmp/api-tos.txt http://localhost:8080/api/admin/settings/:ApiTermsOfUse`` +Specify a URL where users can read your Privacy Policy, linked from the bottom of the page. -:SolrHostColonPort ------------------- +``curl -X PUT -d http://best-practices.dataverse.org/harvard-policies/harvard-privacy-policy.html http://localhost:8080/api/admin/settings/:ApplicationPrivacyPolicyUrl`` -Set ``SolrHostColonPort`` to override ``localhost:8983``. +:ApiTermsOfUse +++++++++++++++ -``curl -X PUT -d localhost:8983 http://localhost:8080/api/admin/settings/:SolrHostColonPort`` +Specify a URL where users can read your API Terms of Use. -:SearchHighlightFragmentSize ----------------------------- +``curl -X PUT -d http://best-practices.dataverse.org/harvard-policies/harvard-api-tou.html http://localhost:8080/api/admin/settings/:ApiTermsOfUse`` + +:GuidesBaseUrl +++++++++++++++ -Set ``SearchHighlightFragmentSize`` to override the default value of 100 from https://wiki.apache.org/solr/HighlightingParameters#hl.fragsize +Set ``GuidesBaseUrl`` to override the default value "http://guides.dataverse.org". If you are interested in writing your own version of the guides, you may find the :doc:`/developers/documentation` section of the Developer Guide helpful. -``curl -X PUT -d 320 http://localhost:8080/api/admin/settings/:SearchHighlightFragmentSize`` +``curl -X PUT -d http://dataverse.example.edu http://localhost:8080/api/admin/settings/:GuidesBaseUrl`` -:ShibEnabled ------------- +:StatusMessageHeader +++++++++++++++++++++ -This setting is experimental per :doc:`/installation/shibboleth`. +For dynamically adding information to the top of every page. For example, "For testing only..." at the top of https://demo.dataverse.org is set with this: + +``curl -X PUT -d "For testing only..." http://localhost:8080/api/admin/settings/:StatusMessageHeader`` :MaxFileUploadSizeInBytes -------------------------- ++++++++++++++++++++++++++ Set `MaxFileUploadSizeInBytes` to "2147483648", for example, to limit the size of files uploaded to 2 GB. Notes: @@ -61,72 +294,89 @@ Notes: ``curl -X PUT -d 2147483648 http://localhost:8080/api/admin/settings/:MaxFileUploadSizeInBytes`` -:GuidesBaseUrl --------------- +:TabularIngestSizeLimit ++++++++++++++++++++++++ -Set ``GuidesBaseUrl`` to override the default value "http://guides.dataverse.org". +Threshold in bytes for limiting whether or not "ingest" it attempted for tabular files (which can be resource intensive). For example, with the below in place, files greater than 2 GB in size will not go through the ingest process: -``curl -X PUT -d http://dataverse.example.edu http://localhost:8080/api/admin/settings/:GuidesBaseUrl`` +``curl -X PUT -d 2000000000 http://localhost:8080/api/admin/settings/:TabularIngestSizeLimit`` -:GeoconnectCreateEditMaps -------------------------- +(You can set this value to 0 to prevent files from being ingested at all.) -Set ``GeoconnectCreateEditMaps`` to true to allow the user to create GeoConnect Maps. This boolean effects whether the user sees the map button on the dataset page and if the ingest will create a shape file. +You can overide this global setting on a per-format basis for the following formats: -``curl -X PUT -d true http://localhost:8080/api/admin/settings/:GeoconnectCreateEditMaps`` +- dta +- por +- sav +- Rdata +- CSV +- xlsx -:GeoconnectViewMaps -------------------- +For example, if you want your installation of Dataverse to not attempt to ingest Rdata files larger that 1 MB, use this setting: -Set ``GeoconnectViewMaps`` to true to allow a user to view existing maps. This boolean effects whether a user will see the "Explore" button. +``curl -X PUT -d 1000000 http://localhost:8080/api/admin/settings/:TabularIngestSizeLimit:Rdata`` -``curl -X PUT -d true http://localhost:8080/api/admin/settings/:GeoconnectViewMaps`` +:ZipUploadFilesLimit +++++++++++++++++++++ +Limit the number of files in a zip that Dataverse will accept. -JVM Options -+++++++++++ +:GoogleAnalyticsCode +++++++++++++++++++++ -dataverse.fqdn --------------- +For setting up Google Analytics for your Dataverse installation. -If the Dataverse server has multiple DNS names, this option specifies the one to be used as the "official" host name. For example, you may want to have dataverse.foobar.edu, and not the less appealling server-123.socsci.foobar.edu to appear exclusively in all the registered global identifiers, Data Deposit API records, etc. +:SolrHostColonPort +++++++++++++++++++ -To change the option on the command line: +By default Dataverse will attempt to connect to Solr on port 8983 on localhost. Use this setting to change the hostname or port. -``asadmin delete-jvm-options "-Ddataverse.fqdn=old.example.com"`` +``curl -X PUT -d localhost:8983 http://localhost:8080/api/admin/settings/:SolrHostColonPort`` -``asadmin create-jvm-options "-Ddataverse.fqdn=dataverse.example.com"`` +:SignUpUrl +++++++++++ -The ``dataverse.fqdn`` JVM option also affects the password reset feature. +The relative path URL to which users will be sent after signup. The default setting is below. -| Do note that whenever the system needs to form a service URL, by default, it will be formed with ``https://`` and port 443. I.e., -| ``https://{dataverse.fqdn}/`` -| If that does not suit your setup, you can define an additional option - +``curl -X PUT -d true /dataverseuser.xhtml?editMode=CREATE http://localhost:8080/api/admin/settings/:SignUpUrl`` -dataverse.siteUrl ------------------ +:TwoRavensUrl ++++++++++++++ -| and specify the alternative protocol and port number. -| For example, configured in domain.xml: -| ``-Ddataverse.fqdn=dataverse.foobar.edu`` -| ``-Ddataverse.siteUrl=http://${dataverse.fqdn}:8080`` +The location of your TwoRavens installation. +:GeoconnectCreateEditMaps ++++++++++++++++++++++++++ -dataverse.auth.password-reset-timeout-in-minutes ------------------------------------------------- +Set ``GeoconnectCreateEditMaps`` to true to allow the user to create GeoConnect Maps. This boolean effects whether the user sees the map button on the dataset page and if the ingest will create a shape file. -Set the ``dataverse.auth.password-reset-timeout-in-minutes`` option if you'd like to override the default value put into place by the installer. +``curl -X PUT -d true http://localhost:8080/api/admin/settings/:GeoconnectCreateEditMaps`` -Dropbox Configuration -++++++++++++++++++++++ +:GeoconnectViewMaps ++++++++++++++++++++ -- Add JVM option in the domain.xml: -``asadmin create-jvm-options "-Ddataverse.dropbox.key="`` +Set ``GeoconnectViewMaps`` to true to allow a user to view existing maps. This boolean effects whether a user will see the "Explore" button. +``curl -X PUT -d true http://localhost:8080/api/admin/settings/:GeoconnectViewMaps`` -Solr -++++ +:SearchHighlightFragmentSize +++++++++++++++++++++++++++++ + +Set ``SearchHighlightFragmentSize`` to override the default value of 100 from https://wiki.apache.org/solr/HighlightingParameters#hl.fragsize . In practice, a value of "320" seemed to fix the issue at https://github.com/IQSS/dataverse/issues/2191 + +``curl -X PUT -d 320 http://localhost:8080/api/admin/settings/:SearchHighlightFragmentSize`` + +:ScrubMigrationData ++++++++++++++++++++ + +Allow for migration of non-conformant data (especially dates) from DVN 3.x to Dataverse 4. + +:ShibEnabled +++++++++++++ + +This setting is experimental per :doc:`/installation/shibboleth`. -The :doc:`prerequisites` section explained that Dataverse requires a specific Solr schema file called `schema.xml` that can be found in the Dataverse distribution. You should have already replaced the default `example/solr/collection1/conf/schema.xml` file that ships with Solr. +:AllowSignUp +++++++++++++ -If ``WARN org.eclipse.jetty.http.HttpParser – HttpParser Full for /127.0.0.1:8983`` appears in the Solr log, adding ``8192`` (or a higher number of bytes) to Solr's jetty.xml in the section matching the XPath expression ``//Call[@name='addConnector']/Arg/New[@class='org.eclipse.jetty.server.bio.SocketConnector']`` may resolve the issue. See also https://support.lucidworks.com/hc/en-us/articles/201424796-Error-when-submitting-large-query-strings- +Set to false to disallow local accounts to be created if you are using :doc:`shibboleth` but not for production use until https://github.com/IQSS/dataverse/issues/2838 has been fixed. diff --git a/doc/sphinx-guides/source/installation/installation-main.rst b/doc/sphinx-guides/source/installation/installation-main.rst index 47c73834a8f..cf11f0ca7c6 100755 --- a/doc/sphinx-guides/source/installation/installation-main.rst +++ b/doc/sphinx-guides/source/installation/installation-main.rst @@ -40,33 +40,52 @@ The script is to a large degree a derivative of the old installer from DVN 3.x. All the Glassfish configuration tasks performed by the installer are isolated in the shell script ``dvinstall/glassfish-setup.sh`` (as ``asadmin`` commands). -As the installer finishes, it mentions a script called ``post-install-api-block.sh`` which is **very important** to execute for any production installation of Dataverse. +As the installer finishes, it mentions a script called ``post-install-api-block.sh`` which is **very important** to execute for any production installation of Dataverse. Security will be covered in :doc:`config` section but for now, let's make sure your installation is working. Logging In ---------- Out of the box, Glassfish runs on port 8080 and 8181 rather than 80 and 443, respectively, so visiting http://localhost:8080 (substituting your hostname) should bring up a login page. See the :doc:`shibboleth` page for more on ports, but for now, let's confirm we can log in by using port 8080. Poke a temporary hole in your firewall. -Dataverse Admin Account -+++++++++++++++++++++++ +Superuser Account ++++++++++++++++++ -Now that you've run the application installer and have your own Dataverse instance, you need to configure the Dataverse Administrator user. -By default installer pre-sets the Admin credentials as follows: +We'll use the superuser account created by the installer to make sure you can log into Dataverse. For more on the difference between being a superuser and having the "Admin" role, read about configuring the root dataverse in the :doc:`config` section. -.. code-block:: none +(The ``dvinstall/setup-all.sh`` script, which is called by the installer sets the password for the superuser account account and the username and email address come from a file it references at ``dvinstall/data/user-admin.json``.) - First Name: Dataverse - Last Name: Admin - Affiliation: Dataverse.org - Position: Admin - Email: dataverse@mailinator.com +Use the following credentials to log in: -Log in as the user dataverseAdmin with the password "admin" and change these values to suit your installation. - -(Alteratively, you can modify the file ``dvinstall/data/user-admin.json`` in the installer bundle **before** you run the installer. The password is in ``dvinstall/setup-all.sh``, which references this JSON file.) +- URL: http://localhost:8080 +- username: dataverseAdmin +- password: admin Congratulations! You have a working Dataverse installation. Soon you'll be tweeting at `@dataverseorg `_ asking to be added to the map at http://dataverse.org :) -Trouble? Please get in touch as explained in the :doc:`intro`. +(While you're logged in, you should go ahead and change the email address of the dataverseAdmin account to a real one rather than "dataverse@mailinator.com" so that you receive notifications.) + +Trouble? See if you find an answer in the troubleshooting section below. Next you'll want to check out the :doc:`config` section. + +Troubleshooting +--------------- + +If the following doesn't apply, please get in touch as explained in the :doc:`intro`. You may be asked to provide ``glassfish4/glassfish/domains/domain1/logs/server.log`` for debugging. + +Dataset Cannot Be Published ++++++++++++++++++++++++++++ + +Check to make sure you used a fully qualified domain name when installing Dataverse. You can change the ``dataverse.fqdn`` JVM option after the fact per the :doc:`config` section. + +Problems Sending Email +++++++++++++++++++++++ + +You can confirm the SMTP server being used with this command: + +``asadmin get server.resources.mail-resource.mail/notifyMailSession.host`` + +UnknownHostException While Deploying +++++++++++++++++++++++++++++++++++++ + +If you are seeing "Caused by: java.net.UnknownHostException: myhost: Name or service not known" in server.log and your hostname is "myhost" the problem is likely that "myhost" doesn't appear in ``/etc/hosts``. See also http://stackoverflow.com/questions/21817809/glassfish-exception-during-deployment-project-with-stateful-ejb/21850873#21850873 diff --git a/doc/sphinx-guides/source/installation/intro.rst b/doc/sphinx-guides/source/installation/intro.rst index 0a03c9ba92c..f3a2d226fb0 100644 --- a/doc/sphinx-guides/source/installation/intro.rst +++ b/doc/sphinx-guides/source/installation/intro.rst @@ -11,8 +11,6 @@ If you are installing Dataverse for the first time, please proceed to the :doc:` Jump ahead to :doc:`config` or :doc:`upgrading` for an existing Dataverse installation. -Features designated as "superuser only" are covered under :doc:`administration`. - Intended Audience ----------------- diff --git a/doc/sphinx-guides/source/installation/prep.rst b/doc/sphinx-guides/source/installation/prep.rst index 522944a5677..76c224b40bb 100644 --- a/doc/sphinx-guides/source/installation/prep.rst +++ b/doc/sphinx-guides/source/installation/prep.rst @@ -6,7 +6,7 @@ Preparation > "What are you preparing? You're always preparing! Just go!" -- Spaceballs -We'll try to get you up and running as quicky as possible but we thought you might like to hear about your opinons. :) +We'll try to get you up and running as quicky as possible, but we thought you might like to hear about your options. :) .. contents:: :local: @@ -35,7 +35,7 @@ There are some community-lead projects to use configuration management tools suc - https://github.com/IQSS/dataverse-puppet - https://github.com/IQSS/dataverse-ansible -The Dataverse development team is happy to "bless" additional community efforts along these lines (i.e. Docker, Chef, Salt, etc.) by creating a repo under the IQSS organization. +The Dataverse development team is happy to "bless" additional community efforts along these lines (i.e. Docker, Chef, Salt, etc.) by creating a repo under https://github.com/IQSS and managing team access. Dataverse permits a fair amount of flexibility in where you choose to install the various components. The diagram below shows a load balancer, multiple proxies and web servers, redundant database servers, and offloading of potentially resource intensive work to a separate server. A setup such as this is advanced enough to be considered out of scope for this guide but you are welcome to ask questions about similar configurations via the support channels listed in the :doc:`intro`.