be4311c07e14feb728abc6425ee606ffaa611a58 markd Fri Jan 22 06:46:58 2021 -0800 merge with master diff --git src/product/mirrorManual.txt src/product/mirrorManual.txt index e361c7d..02eed3b 100644 --- src/product/mirrorManual.txt +++ src/product/mirrorManual.txt @@ -1,24 +1,24 @@ % Manual installation of the UCSC Genome Browser on a Unix server # Overview of the Genome Browser directories and databases The genome browser requires only Apache and MySQL and uses these directories: - static html files: we typically keep them under /usr/local/apache/htdocs and configure Apache to load them from there, to avoid conflicts with the - Linux distribution's default location /var/www/html + distribution of the Linux default location /var/www/html - MySQL databases: most of them are read-only, except the `hgcentral` database which is read-write. Most linux distributions keep these under /var/lib/mysql - static genome data files in /gbdb/ - binary CGI programs that generate images from the MySQL and /gbdb files and write them into the `trash` directory (see below). We modify our Apache config to load CGIs from /usr/local/apache/cgi-bin, so as to not conflict with the default directory of the Linux distribution - a directory for temp files called `trash`, located in the parent directory of the CGI programs, usually /usr/local/apache/trash - a small text file hg.conf in the same directory as the CGI programs, with information on how to connect to MySQL, the location of the other directories and various other settings, on our machines the location of this file is /usr/local/apache/cgi-bin/hg.conf - uploaded custom data gets written by the CGI programs into MySQL databases in the database `customtrash` and also into files under /usr/local/apache/trash @@ -483,31 +483,31 @@ IDENTIFIED BY 'update';" mysql done The cgi-bin binaries obtain their MySQL identities from the hg.conf file in the cgi-bin directory. The file in this directory: src/product/ex.hg.conf demonstrates the use of the "readonly" user for genome database access and the "readwrite" user for hgcentral database access. 4. The hgsql command: Developers can access the browser databases via the 'hgsql' command which can be built in the source-tree at: kent/src/hg/hgsql/ This 'hgsql' command provides a convenient front-end to - the standard 'mysql' command by reading the user's ~/.hg.conf + the standard 'mysql'' command by reading the user's ~/.hg.conf file to provide access to the browser databases with the appropriate identity. Each user creates a ~/.hg.conf file (same format as the above mentioned cgi-bin/hg.conf file) and the specified database user identity is used for accesses to the browser databases. This same function of reading ~/.hg.conf for database access is built into all the source-tree binaries which modify the genome databases. The above example hg.conf could be used as a user's ~/.hg.conf file with the change of db.user, db.password, central.user, and central.password to be the fully permitted read-write user: db.user=browser @@ -662,31 +662,32 @@ REQUIRE x509; There are more-specific requirements that may be added: GRANT ALL PRIVILEGES ON *.* TO 'someuser'@'%' REQUIRE SUBJECT '/C=US/ST=CA/L=Santa Cruz/O=YourCompany/OU=YourDivision/CN=someuser/emailAddress=someuser@YourCompany.com' AND ISSUER '/C=US/ST=CA/L=Santa Cruz/O=YourCompany/OU=YourDivision/CN=YourCompanyCA/emailAddress=admin@YourCompany.com' AND CIPHER 'DHE-RSA-AES256-SHA'; You can see the cert details like this: openssl x509 -in /somepath/someuser-cert.pem -text In later versions of MySQL, it is a requirement that the CN of the CA cert must DIFFER from the CN of the user and server certs. - Further MySQL SSL documentation is available from <https://dev.mysql.com/doc/refman/5.6/en/ssl-connections.html> + Further MySQL SSL documentation is available from +<https://dev.mysql.com/doc/refman/5.6/en/creating-ssl-files-using-openssl.html> # Adding a custom genome to the browser Please note that setting up an [assembly hub](http://genomewiki.ucsc.edu/index.php/Assembly_Hubs) is a lot easier than adding a genome to a local mirror. The browser can be made to operate with a bare minimum of tables for the purpose of demonstrating the CGI binaries are functioning. The only tables you need to load for this are: 1. all tables in the hgcentral database 2. six tables in the human genome Create an empty hgcentral database: @@ -1093,33 +1094,33 @@ cartUsualString. The hg18 hgTracks config page generates a GET URL that is too long for FireFox, so after debugging hgTables, you will probably want to add &formMethod=POST to an URL (or clear cart, load session etc). One thing that does not work with GET is "upload file" inputs. # Local Git repository Use the following procedures to create your own personal copy of the kent source tree where you can have your own edits that are not part of the development at UCSC. This is useful for mirror sites that have their own customizations in the source tree for local circumstances. Install Git software version 1.6.2.2 or later. See the Git Community Handbook - installation (<http://book.git-scm.com/2_installing_git.html>) and setup - (<http://book.git-scm.com/2_setup_and_initialization.html>) instructions, as well - as our Installing git (<http://genomewiki.ucsc.edu/index.php/Installing_git>) + installation (<https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>) and setup + (<href='https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup>) instructions, as well + as our Installing Git (<http://genomewiki.ucsc.edu/index.php/Installing_git>) Genomewiki page. Start an initial Git local repository: git clone git://genome-source.soe.ucsc.edu/kent.git or, if a firewall prevents git daemon port 9418, use: git clone http://genome-source.soe.ucsc.edu/kent.git The kent source tree will be imported to the current working directory in a directory named ./kent/. Track the beta branch at UCSC repository: Most users want to use the beta branch, which has tested, released versions of the browser. To create a beta tracking branch: @@ -1405,15 +1406,64 @@ "error". The apache user must have read/write permissions for the pending/ directory, and at least read permissions for the cramRef/ and error/ directories. If you plan to manually load all CRAM reference sequences for your tracks into the cramRef directory, track support is now complete. If you prefer to have reference sequences automatically downloaded and placed in that directory (e.g., for user-submitted custom tracks), continue to step 3. 3. Add a cron job to run a script that parses files in the cramRef/pending/ directory, downloads the corresponding reference sequence files, and places those sequence files in cramRef/. Error messages during file retrieval should be placed in cramRef/error/. An example script is provided in this repository at kent/src/product/scripts/fetchCramReference.sh. The account that runs this script must have read/write permissions for the cramRef/, cramRef/pending/, and cramRef/error/ directories. + +# Using FreeType font support for anti-aliased text + +The Genome Browser can use a set of hard-coded Type1 fonts for text display +in hgTracks. The fonts are NOT distributed as part of the Genome Browser files +but they exist natively on the UNIX systems we use in our production environment. +To support FreeType font drawing on your system you may need to install these files if they +are not already present. On most systems, they exist in one of three directories: + + /usr/share/X11/fonts/urw-fonts + /usr/share/fonts/default/Type1 + /usr/share/fonts/type1/gsfonts + +To turn on the FreeType font rendering you need to add this line to your hg.conf file: + + freeType=on + +By default, the Genome Browser looks in the directory + + /usr/share/fonts/default/Type1 + +for the font files it expects to find. If you have these fonts in a different directory, you need +to add this line to your hg.conf file: + + freeTypeDir='<apache accessible directory path with fonts in it>' + +The names of the font files that the Genome Browser expects and their md5sums are in the following table: + + 5624bc04bbd862287bda3c44b15e90d6 a010013l.pfb + 6883f53d0d140f972480f179bb5e4e3b a010015l.pfb + db21f79bac990fa7e3de6d4cc6f54020 a010033l.pfb + c3d0c3af6bc183010204ca923fb98e83 a010035l.pfb + 33265074c9c45c356f90de9cc47259b3 n019003l.pfb + 9d07b8658622c2e0127628c87fdb9661 n019004l.pfb + df59ecc7bd232d2355786fd644f13baa n019023l.pfb + 9f2d4377d9eea95dfdfa705c83a39464 n019024l.pfb + 8f75382bd2620a20aaeb06ab8c591e8f n019043l.pfb + 28bb40d1700909b2509e2125a1963e2c n019044l.pfb + adf4d5565bec1170f0a5810c6984ff55 n019063l.pfb + 57e1a49c39a546c2883375df12111816 n019064l.pfb + 84e347c88eff2e77ed40b020b457bafe n021003l.pfb + 8721c1175d907d7d484bdaa91d4533ad n021004l.pfb + eef0367afaa10b929e528c40c980b941 n021023l.pfb + 7af41ff3536fadcdc27eb9e5cc1c32d3 n021024l.pfb + db95b702b81c12df1f91d15c8a6c3191 n022003l.pfb + e97c9af68414fabe157af711b7691df7 n022004l.pfb + f13fb8e581426a1ffa5fc12b10ad0f34 n022023l.pfb + f3cd9244150f086434b62d5c5bb559b0 n022024l.pfb + 30aef717b7c68a6b6b7760b764fbd01c z003034l.pfb