Uploaded image for project: 'Data Management'
  1. Data Management
  2. DM-649

framework for documenting "how to run qserv"

    XMLWordPrintable

    Details

    • Type: Story
    • Status: Done
    • Resolution: Done
    • Fix Version/s: None
    • Component/s: Qserv
    • Labels:
      None
    • Story Points:
      2.5
    • Sprint:
      DB_S14_06, DB_S14_07, DB_S14_08
    • Team:
      Data Access and Database

      Description

      We need to have permanent location for how-to-run-qserv, currently we keep it in https://dev.lsstcorp.org/trac/wiki/db/Qserv/RedesignFY2014/Hackathon2/howToRunQserv. It should be in the code repo. Need to decide on how we format it, and need to expose it on our Qserv trac/confluence pages

        Attachments

          Issue Links

            Activity

            Hide
            jbecla Jacek Becla added a comment -

            Fabrice, I just remembered one more thing: the "-r <qserv run dir>" option is very handy, it needs to be well documented (and explained that the default is set to ~/qserv-run)

            Show
            jbecla Jacek Becla added a comment - Fabrice, I just remembered one more thing: the "-r <qserv run dir>" option is very handy, it needs to be well documented (and explained that the default is set to ~/qserv-run)
            Hide
            jbecla Jacek Becla added a comment -

            Fabrice, I am pasting comments from Daniel here. I believe this completes the review

            "Welcome to Qserv's documentation!" should just be "Qserv 2014_08.0 documentation <http://lsst-web.ncsa.illinois.edu/%7Efjammes/qserv-doc/u.fjammes.DM-649-gee2bed707c/index.html#>" or just "Qserv documentation"

            "Software architecture" --> "Administration reference"
            ---------------------------
            quickstart page:

            "FOR DEVELOPERS:..." --> "This procedure is for RELEASED and PUBLISHED qserv software. Developers interested in modifying code or running unreleased versions should see Quick start guide for developers "

            Configuration
            The code block should just be:
            qserv-configure.py --all

            The alert:"Qserv commands listed below provides advanced options, use –help option to discover how to use it." is unnecessary. Just put a note below the command saying something like: "For more options, run qserv-configure.py --help". In the future, we should at least list, of not document some of the options. The whole point of this page is to "document".

            In general, the alert blocks ( that have ) should only be used to point out "gotchas" or ways in which the reader may possibly screw up. The block at the top of the page is appropriate--it just says "Hey, watch out" and is not really adding to the essentials of the page.

            Integration tests
            "Integration tests" -> "Testing"

            The "Default value for ..." alert should probably be a comment in the code block below.

            Quick start guide for developers

            You want something to say: "Using Qserv with your own custom code or arbitrary versions can be done by connecting your local git clone with an existing released qserv installation (e.g. from Quick start guide). This should be stated above "Setup current Qserv version in eups".

            Setup current Qserv version in eups:

            text should say: "These commands point the infrastructure of an existing qserv installation to work with a local Qserv git repository."

            below code block:
            Once the qserv eups stack is integrated with your local Qserv repository, you will need to re-configure and (if desired) re-test as described in the Quick start guide.

            I'll have to look at "Software architecture" later-it's a bit messy and not really user documentation-it looks like like a Trac/JIRA ticket or epic.

            Hope this helps,
            -Daniel

            Show
            jbecla Jacek Becla added a comment - Fabrice, I am pasting comments from Daniel here. I believe this completes the review "Welcome to Qserv's documentation!" should just be "Qserv 2014_08.0 documentation < http://lsst-web.ncsa.illinois.edu/%7Efjammes/qserv-doc/u.fjammes.DM-649-gee2bed707c/index.html# >" or just "Qserv documentation" "Software architecture" --> "Administration reference" --------------------------- quickstart page: "FOR DEVELOPERS:..." --> "This procedure is for RELEASED and PUBLISHED qserv software. Developers interested in modifying code or running unreleased versions should see Quick start guide for developers " Configuration The code block should just be: qserv-configure.py --all The alert:"Qserv commands listed below provides advanced options, use –help option to discover how to use it." is unnecessary. Just put a note below the command saying something like: "For more options, run qserv-configure.py --help". In the future, we should at least list, of not document some of the options. The whole point of this page is to "document". In general, the alert blocks ( that have ) should only be used to point out "gotchas" or ways in which the reader may possibly screw up. The block at the top of the page is appropriate--it just says "Hey, watch out" and is not really adding to the essentials of the page. Integration tests "Integration tests" -> "Testing" The "Default value for ..." alert should probably be a comment in the code block below. Quick start guide for developers You want something to say: "Using Qserv with your own custom code or arbitrary versions can be done by connecting your local git clone with an existing released qserv installation (e.g. from Quick start guide). This should be stated above "Setup current Qserv version in eups". Setup current Qserv version in eups: text should say: "These commands point the infrastructure of an existing qserv installation to work with a local Qserv git repository." below code block: Once the qserv eups stack is integrated with your local Qserv repository, you will need to re-configure and (if desired) re-test as described in the Quick start guide. I'll have to look at "Software architecture" later- it's a bit messy and not really user documentation -it looks like like a Trac/JIRA ticket or epic. Hope this helps, -Daniel
            Hide
            salnikov Andy Salnikov added a comment -

            Looking at the documentation again it occurs to me that instructions as written now are for installing the most recent qserv version. Should they have explicit release name in the "eups distrib unstall qserv" and "setup qserv"?

            Show
            salnikov Andy Salnikov added a comment - Looking at the documentation again it occurs to me that instructions as written now are for installing the most recent qserv version. Should they have explicit release name in the "eups distrib unstall qserv" and "setup qserv"?
            Hide
            salnikov Andy Salnikov added a comment -

            One more comment (sorry I continue commenting on a closed issue, I don't feel this deserves a new ticket yet). I managed to build and run qserv on Ubuntu 12.04 clean server install after I added these packages:

            make
            g++
            libz-dev
            gettext
            flex
            bison
            scons
            libreadline-dev
            libncurses5-dev
            cmake
            python-dev
            python-numpy
            swig
            libbz2-dev
            python-setuptools
            pkg-config
            libglib2.0-dev
            openjdk-7-jdk

            Show
            salnikov Andy Salnikov added a comment - One more comment (sorry I continue commenting on a closed issue, I don't feel this deserves a new ticket yet). I managed to build and run qserv on Ubuntu 12.04 clean server install after I added these packages: make g++ libz-dev gettext flex bison scons libreadline-dev libncurses5-dev cmake python-dev python-numpy swig libbz2-dev python-setuptools pkg-config libglib2.0-dev openjdk-7-jdk
            Hide
            jammes Fabrice Jammes added a comment -

            Hi, i've integrated most of your post-review comment directly into master. About Daniel comments, i've only replaced "existing released qserv installation " with "eups software stack containing Qserv dependencies". Indeed, in last developer doc updates, it is no more required to install a Qserv release prior to installing it from user git repository.

            Show
            jammes Fabrice Jammes added a comment - Hi, i've integrated most of your post-review comment directly into master. About Daniel comments, i've only replaced "existing released qserv installation " with "eups software stack containing Qserv dependencies". Indeed, in last developer doc updates, it is no more required to install a Qserv release prior to installing it from user git repository.

              People

              Assignee:
              jammes Fabrice Jammes
              Reporter:
              fritzm Fritz Mueller
              Reviewers:
              Daniel Wang [X] (Inactive), Jacek Becla
              Watchers:
              Andy Salnikov, Daniel Wang [X] (Inactive), Fabrice Jammes, Jacek Becla, Kian-Tat Lim
              Votes:
              0 Vote for this issue
              Watchers:
              5 Start watching this issue

                Dates

                Created:
                Updated:
                Resolved:

                  CI Builds

                  No builds found.