Enabling hgLogin: Difference between revisions

From genomewiki
Jump to navigationJump to search
No edit summary
(→‎Enabling hgLogin: clarified the instruction to leave cookie names the same as they were on genomewiki (RM #9662))
 
(18 intermediate revisions by 4 users not shown)
Line 1: Line 1:
Here are the steps necessary to enable the hgLogin CGI on a Genome Browser mirror site and use the user database at genome.ucsc.edu:
==Introduction==


<ol>
Prior to version 268, the UCSC Genome Browser was using the UCSC Genome Wiki website
<li>Locate the genome browser configuration file "hg.conf" in your /cgi-bin directory.</li>
to handle the sign up, login, and logout functions for the session manager. In this context, for a mirror site
<li>Add the statement "login.systemName=hgLogin CGI" to the hg.conf file.</li>
to save sessions locally, the mirror site must have had the sign-in function provided by a simulated or locally-installed
<li>Also in the hg.conf file, change the host value in the "wiki.host" entry to point to your mirror browser.</li>
mediawiki server.
As an example, the two entries in the hg.conf file for the Genome Browser are:
  login.systemName=hgLogin CGI
  wiki.host=genome.ucsc.edu


Starting with v268, the UCSC Genome Browser introduced the '''hgLogin''' CGI to replace Genomewiki as the login manager. The user management
functions are now handled by the built-in '''hgLogin''' CGI together with the '''gbMembers''' table in the '''hgcentral''' database.
Starting from v269, mirror sites can use the '''hgLogin''' CGI to handle the user management directly without mediawiki.


<li>Since the hgLogin CGI uses the same cookies as mediawiki used to, please '''do not modify''' these two configuration parameters:</li>
==Backward compatibility==
  wiki.userNameCookie=wikidb_mw1_UserName     
  wiki.loggedInCookie=wikidb_mw1_UserID 
The '''hgLogin''' CGI is designed to maintain complete backward compatibility with the genomewiki login system:


</ol>
* For current UCSC Genome Browser users, the transition from genomewiki to '''hgLogin''' is transparent. The username, password, email address and, most importantly, all the saved sessions are preserved. The user will notice no functional change. 
The fact that the hgSession and hgLogin CGIs use the same cookies that used to be used by mediawiki provides complete backwards compatibility to current mirror sites with sign-in function (via a simulated- or locally-installed mediawiki server).  
* The '''hgSession''' and '''hgLogin''' CGIs are designed to use the same cookies that are used by genomewiki.  This design provides complete backwards compatibility to current mirror sites using the login function (via a simulated- or locally-installed mediawiki server).  When '''hgLogin''' is not enabled, all browser functions will continue to work as before.


As long as hgLogin is not enabled, all browser functions and current sign-in functions will work as before.
==Enabling hgLogin==


As always, if you run into difficulties, please do not hesitate to contact our mirror site mail list at [mailto:genome-mirror@soe.ucsc.edu genome-mirror@soe.ucsc.edu].
Procedure to enable the '''hgLogin''' CGI on a Genome Browser mirror:  


* Locate the genome browser configuration file '''hg.conf''' in your '''/cgi-bin/''' directory.
* Add the statement '''login.systemName=hgLogin CGI''' to the '''hg.conf''' file.
* Also in the '''hg.conf''' file, change the host value in the "wiki.host" entry to point to your mirror browser host running the '''hgLogin''' CGI. The host should be in the same domain as value set in "central.domain". For example, if '''central.doman=.university.edu''' then set '''wiki.host=mylab.university.edu'''
* If you are migrating from the old genomewiki login system and want the '''hgLogin''' CGI to use the same cookies as did the genomewiki, do not modify these two configuration parameters:
wiki.userNameCookie=wikidb_mw1_UserName     
wiki.loggedInCookie=wikidb_mw1_UserID
Otherwise, these parameters can be set to any name:
wiki.userNameCookie=myLabCookieNameForUserName
wiki.loggedInCookie=myLabCookieNameForUseID
* Add the 4 login.xxxxxx parameters for the user interface (UI) headings '''(browserName)''' and text string used in emails '''(login.xxxxxx)''' send out to the user.  You should set them to appropriate local values. 
To summarize, the following parameters should be in '''hg.conf''' to enable '''hgLogin''':
# required to use hgLogin
login.systemName=hgLogin CGI 
# url to server hosting hgLogin
wiki.host=mylab.university.edu
# name of cookie holding username
wiki.userNameCookie=myLabCookieNameForUserName
# name of cookie holding user id
wiki.loggedInCookie=myLabCookieNameForUseID
# title of host of browser, this text will be shown in the user interface of the login/sign up screens
login.browserName=myLab Genome Browser
# base url of browser install
login.browserAddr=http://mylab.university.edu
# signature written at the bottom of hgLogin system emails
login.mailSignature=My Lab browser administrator
# from/return email address used for system emails
login.mailReturnAddr=browserAdministrator@mylab.university.edu
==Migration to hgLogin==
Mirror sites currently operating a local login function can replace the local system with the '''hgLogin''' CGI.
Migrate the user information to the '''gbMembers''' table in hgcentral, then edit the '''hg.conf''' to enable '''hgLogin'''.
Procedure to migrate from mediawiki to '''hgLogin''':
* The gbMembers table structure is supplied in the download copy of the '''hgcentral''' database: [http://hgdownload.cse.ucsc.edu/admin/hgcentral.sql hgcentral.sql]
* Use the '''CREATE TABLE IF NOT EXISTS 'gbMembers' (...)''' statement from the '''hgcentral.sql''' file.
* Determine the name of the database and table used by mediawiki from the mediaWiki configuration file '''LocalSettings.php'''. Assuming the configuration has:
$wgDBname          = "wikidb";
$wgDBprefix        = "mw1_";
Then, the table name '''mw1_user''' and database name '''wikidb''' are used.
* Export the '''user''' table into a file '''wikidb.user.tab''':
hgsql -e "select user_id,user_name,user_real_name,user_password,user_email,user_touched,user_email_authenticated
      from mw1_user;"  wikidb > wikidb.user.tab
* Import the '''wikidb.user.tab''' to '''hgcentral.gbMembers''':
hgsql -e "LOAD DATA LOCAL INFILE 'wikidb.user.tab' INTO TABLE gbMembers FIELDS TERMINATED BY '\t'
      LINES TERMINATED BY '\n' IGNORE 1 LINES;"
* Set the two status fields:
hgsql -e "update gbMembers set passwordChangeRequired='N';" hgcentral
hgsql -e "update gbMembers set accountActivated='Y';" hgcentral
* Enable '''hgLogin''' with the modifications to '''hg.conf''' as described above.


[[Category:Mirror Site FAQ]]
[[Category:Mirror Site FAQ]]

Latest revision as of 01:11, 6 April 2013

Introduction

Prior to version 268, the UCSC Genome Browser was using the UCSC Genome Wiki website to handle the sign up, login, and logout functions for the session manager. In this context, for a mirror site to save sessions locally, the mirror site must have had the sign-in function provided by a simulated or locally-installed mediawiki server.

Starting with v268, the UCSC Genome Browser introduced the hgLogin CGI to replace Genomewiki as the login manager. The user management functions are now handled by the built-in hgLogin CGI together with the gbMembers table in the hgcentral database. Starting from v269, mirror sites can use the hgLogin CGI to handle the user management directly without mediawiki.

Backward compatibility

The hgLogin CGI is designed to maintain complete backward compatibility with the genomewiki login system:

  • For current UCSC Genome Browser users, the transition from genomewiki to hgLogin is transparent. The username, password, email address and, most importantly, all the saved sessions are preserved. The user will notice no functional change.
  • The hgSession and hgLogin CGIs are designed to use the same cookies that are used by genomewiki. This design provides complete backwards compatibility to current mirror sites using the login function (via a simulated- or locally-installed mediawiki server). When hgLogin is not enabled, all browser functions will continue to work as before.

Enabling hgLogin

Procedure to enable the hgLogin CGI on a Genome Browser mirror:

  • Locate the genome browser configuration file hg.conf in your /cgi-bin/ directory.
  • Add the statement login.systemName=hgLogin CGI to the hg.conf file.
  • Also in the hg.conf file, change the host value in the "wiki.host" entry to point to your mirror browser host running the hgLogin CGI. The host should be in the same domain as value set in "central.domain". For example, if central.doman=.university.edu then set wiki.host=mylab.university.edu
  • If you are migrating from the old genomewiki login system and want the hgLogin CGI to use the same cookies as did the genomewiki, do not modify these two configuration parameters:
wiki.userNameCookie=wikidb_mw1_UserName       
wiki.loggedInCookie=wikidb_mw1_UserID

Otherwise, these parameters can be set to any name:

wiki.userNameCookie=myLabCookieNameForUserName
wiki.loggedInCookie=myLabCookieNameForUseID
  • Add the 4 login.xxxxxx parameters for the user interface (UI) headings (browserName) and text string used in emails (login.xxxxxx) send out to the user. You should set them to appropriate local values.

To summarize, the following parameters should be in hg.conf to enable hgLogin:

# required to use hgLogin
login.systemName=hgLogin CGI   

# url to server hosting hgLogin
wiki.host=mylab.university.edu

# name of cookie holding username
wiki.userNameCookie=myLabCookieNameForUserName

# name of cookie holding user id
wiki.loggedInCookie=myLabCookieNameForUseID

# title of host of browser, this text will be shown in the user interface of the login/sign up screens
login.browserName=myLab Genome Browser

# base url of browser install 
login.browserAddr=http://mylab.university.edu

# signature written at the bottom of hgLogin system emails
login.mailSignature=My Lab browser administrator

# from/return email address used for system emails
login.mailReturnAddr=browserAdministrator@mylab.university.edu

Migration to hgLogin

Mirror sites currently operating a local login function can replace the local system with the hgLogin CGI. Migrate the user information to the gbMembers table in hgcentral, then edit the hg.conf to enable hgLogin.

Procedure to migrate from mediawiki to hgLogin:

  • The gbMembers table structure is supplied in the download copy of the hgcentral database: hgcentral.sql
  • Use the CREATE TABLE IF NOT EXISTS 'gbMembers' (...) statement from the hgcentral.sql file.
  • Determine the name of the database and table used by mediawiki from the mediaWiki configuration file LocalSettings.php. Assuming the configuration has:
$wgDBname           = "wikidb";
$wgDBprefix         = "mw1_";

Then, the table name mw1_user and database name wikidb are used.

  • Export the user table into a file wikidb.user.tab:
hgsql -e "select user_id,user_name,user_real_name,user_password,user_email,user_touched,user_email_authenticated 
     from mw1_user;"  wikidb > wikidb.user.tab
  • Import the wikidb.user.tab to hgcentral.gbMembers:
hgsql -e "LOAD DATA LOCAL INFILE 'wikidb.user.tab' INTO TABLE gbMembers FIELDS TERMINATED BY '\t' 
     LINES TERMINATED BY '\n' IGNORE 1 LINES;" 
  • Set the two status fields:
hgsql -e "update gbMembers set passwordChangeRequired='N';" hgcentral
hgsql -e "update gbMembers set accountActivated='Y';" hgcentral
  • Enable hgLogin with the modifications to hg.conf as described above.