Enabling hgLogin: Difference between revisions

From genomewiki
Jump to navigationJump to search
(removing html mark up, using wiki syntax)
(→‎Enabling hgLogin: clarified the instruction to leave cookie names the same as they were on genomewiki (RM #9662))
 
(15 intermediate revisions by 4 users not shown)
Line 1: Line 1:
==Introduction==
==Introduction==


To ensure privacy of saved sessions in the UCSC Genome Browser, a user must log in to the browser before
Prior to version 268, the UCSC Genome Browser was using the UCSC Genome Wiki website
using the session manager. Prior to version 268, the UCSC Genome Browser was using 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 handle the sign up, login, and logout functions for the session manager. Previously, 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  
to save sessions locally, the mirror site must have sign-in function provided by a simulated or locally-installed  
mediawiki server.
mediawiki server.


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


==Backward compatibility==
==Backward compatibility==
   
   
The hgLogin CGI is designed to maintain complete 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.


* For current UCSC Genome Browser user, the transition from genomewiki to hgLogin is transparent. The user name, password, email address and, most importantly, all the saved sessions are preserved. The user will not notice any function change at all. 
* Since the hgSession and hgLogin CGIs are designed to use the same cookies that used to be used by mediawiki.  This design provides complete backwards compatibility to current mirror sites with sign-in function (via a simulated- or locally-installed mediawiki server). As long as hgLogin is not enabled, All browser functions will continue to work as before
==Enabling hgLogin==
==Enabling hgLogin==


Here are the steps necessary to enable the hgLogin CGI on a Genome Browser mirror:
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 "<b>login.systemName=hgLogin CGI</b>" 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 that running the hgLogin CGI. The host should be in the same domain as value set in "central.domain", for example, if "<b>central.doman=.university.edu</b>" then set "<b>wiki.host=mylab.university.edu</b>"
* Since the hgLogin CGI uses the same cookies as mediawiki used to, please do not modify these two configuration parameters:  


* 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.userNameCookie=wikidb_mw1_UserName       
  wiki.loggedInCookie=wikidb_mw1_UserID
  wiki.loggedInCookie=wikidb_mw1_UserID
 
Otherwise, these parameters can be set to any name:
* Add the 4 parameters for the UI headings (browserName) and necessary text string used in emails (hgLogin.xxxxxx) send out to user.  You should set them to any appropriate local values.   
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, You should have the following parameters in hg.conf to enable the hgLogin"
To summarize, the following parameters should be in '''hg.conf''' to enable '''hgLogin''':
  login.systemName=hgLogin CGI
# required to use hgLogin
  login.systemName=hgLogin CGI  
# url to server hosting hgLogin
  wiki.host=mylab.university.edu
  wiki.host=mylab.university.edu
  wiki.userNameCookie=wikidb_mw1_UserName
  wiki.loggedInCookie=wikidb_mw1_UserID
# 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
  login.browserName=myLab Genome Browser
# base url of browser install
  login.browserAddr=http://mylab.university.edu
  login.browserAddr=http://mylab.university.edu
# signature written at the bottom of hgLogin system emails
  login.mailSignature=My Lab browser administrator
  login.mailSignature=My Lab browser administrator
# from/return email address used for system emails
  login.mailReturnAddr=browserAdministrator@mylab.university.edu
  login.mailReturnAddr=browserAdministrator@mylab.university.edu


==Migration to hgLogin==
==Migration to hgLogin==


For current mirror sites with local sign-in function, you can replace
Mirror sites currently operating a local login function can replace the local system with the '''hgLogin''' CGI.
your sign-in system with hgLogin CGI. You need to
Migrate the user information to the '''gbMembers''' table in hgcentral, then edit the '''hg.conf''' to enable '''hgLogin'''.
migrate the user information to gbMembers table in hgcentral first, then edit the hg.conf to enable the hgLogin.


Assuming you are migrating from mediawiki to hgLogin, here are the steps you must take:
Procedure to migrate from mediawiki to '''hgLogin''':


* Understand the structure of the gbMembers table in hgcentral database. Please study the gbMembers table structure in
* The gbMembers table structure is supplied in the download copy of the '''hgcentral''' database: [http://hgdownload.cse.ucsc.edu/admin/hgcentral.sql hgcentral.sql]
http://hgdownload.cse.ucsc.edu/admin/hgcentral.sql
* Use the '''CREATE TABLE IF NOT EXISTS 'gbMembers' (...)''' statement from the '''hgcentral.sql''' file.
* Create the gbMembers table in hgcentral based "REATE TABLE IF NOT EXISTS `gbMembers` (...)" statement in the hgcentral.sql.
* Determine the name of the database and table used by mediawiki from the mediaWiki configuration file '''LocalSettings.php'''. Assuming the configuration has:
* Find out the names of database and table used by mediawiki from the MediaWiki configuration file LocalSettings.php. Assuming the configuration has  
  $wgDBname          = "wikidb";
  $wgDBname          = "wikidb";
  $wgDBprefix        = "mw1_";
  $wgDBprefix        = "mw1_";
Then, the table name "mw1_user" and database name "wikidb" are used.
Then, the table name '''mw1_user''' and database name '''wikidb''' are used.
* Export the user table table wikidb.user.tab using:
* 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  
  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
       from mw1_user;"  wikidb > wikidb.user.tab
* Import the wikidb.user.tab to gbMembers by
* Import the '''wikidb.user.tab''' to '''hgcentral.gbMembers''':
  hgsql -e "LOAD DATA LOCAL INFILE 'wikidb.user.tab' INTO TABLE gbMembers FIELDS TERMINATED BY '\t'  
  hgsql -e "LOAD DATA LOCAL INFILE 'wikidb.user.tab' INTO TABLE gbMembers FIELDS TERMINATED BY '\t'  
       LINES TERMINATED BY '\n' IGNORE 1 LINES;"  
       LINES TERMINATED BY '\n' IGNORE 1 LINES;"  
* Set the two status fields by:
* Set the two status fields:
  hgsql -e "update gbMembers set passwordChangeRequired='N';" hgcentral
  hgsql -e "update gbMembers set passwordChangeRequired='N';" hgcentral
  hgsql -e "update gbMembers set accountActivated='Y';" hgcentral
  hgsql -e "update gbMembers set accountActivated='Y';" hgcentral
* Enable hgLogin by modifying hg.conf as described above.
* 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.