-
Notifications
You must be signed in to change notification settings - Fork 24
Installation instructions details
Planetary is built on top of Drupal. You can get the code you need to install Planetary on Github. Installation is straightforward. The platform is also pretty flexible: Planetary is already in use as the basis of a course discussion forum and an online mathematics encyclopedia. We will be interested to hear how you get on with using the system: feel free to get in touch if you have any comments or questions (or if you want to help improve the code)!
This assumes a LAMP stack. We have some tips for a few platforms.
In addition, although you can mostly follow the instructions here in linear order, we strongly recommend reading this section before you get started.
git clone git://github.com/KWARC/planetary.git
ln -s /home/planetary/planetary /var/www/drupal
cd planetary
chmod a+w sites/default/files
cp sites/default/default.settings.php sites/default/settings.php
chmod a+w sites/default/settings.php
git clone --branch 7.x-5.x http://git.drupal.org/project/drush.git
ln -s /home/planetary/drush/drush /usr/local/bin/drush
We will have a TAR.GZ download available soon as well. In the mean time, if you want one, just ask!
NOTE: the above instructions work well for setting up a development environment. If you want to run a production server, these notes give some advice on a more secure solution for managing uploaded files.
You'll need to create a database for Drupal to use:
$ mysql -u root -p
mysql > CREATE DATABASE drupaldb;
mysql > GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, DROP, INDEX, ALTER
ON drupaldb.* TO 'drupaluser'@'localhost' IDENTIFIED BY 'make-up-a-password';
Note: if you are restoring from a backup, the database, username, and password must match. This information can be found in sites/default/settings.php on the upstream installation.
Stick something like this in a file in /etc/apache2/sites-available and enable it with a2ensite
(or consider the alternatives):
<VirtualHost *:80>
ServerAdmin [email protected]
ServerName xxx.yyy.zzz
DocumentRoot /var/www/drupal/
<Directory /var/www/drupal/>
AllowOverride All
Order allow,deny
allow from all
</Directory>
ErrorLog /var/log/apache2/a.log
CustomLog /var/log/apache2/a.log combined
</VirtualHost>
Now when you visit xxx.yyy.zzz, you can go through a very easy installation process (in particular, this is where you can select and run the "installation profile" we provide). Check the notes just below to decide how to proceed. Finally, once the installation is done, you should run
chmod a-w sites/default/settings.php
We're currently developing an installation profile that will take care of most important configuration steps for you (see this page for details). This installation profile will allow you to build a "PlanetMath clone", see further comments on this topic below. If you're not migrating an legacy !PlanetMath-like site (or doing dev work on a new PlanetMath-like site!), then the installation profile may still be useful to you as a starting place to copy-and-modify to obtain the features you need.
In any event, whether you use the installation profile or not, you will have to run these commands from inside your drupal directory before the installation can proceed to obtain the standard modules that we require.
drush -y dl migrate views features reroute_email references \
pathauto profile2 subform token relation \
relation_select legal userpoints userpoints_nc \
privatemsg content_access ctools delete_all devel backup_migrate commentrss \
nodeaccess wysiwyg views_php sparql filefield_paths date dhtml_menu \
apachesolr apachesolr_views riddler
drush -y dl og-7.x-2.x-dev entityreference-7.x-1.x-dev entity-7.x-1.x-dev \
views_bulk_operations-7.x-3.x-dev captcha-7.x-1.x-dev efq_views-7.x-1.x-dev \
watcher-7.x-1.x-dev rdfx-7.x-2.x-dev
Note that captcha and efq_views don't currently provide a "recommended release", but the ones listed are the latest ones known to work; we're using the latest development version of OG (Organic Groups) along with its dependencies. Other versions where we've indicated a version number tend to have useful recent bug fixes.
In order to get the ARC2 library installed in the right place, once the profile has finished running, you should issue this drush command:
drush en rdfx
In order to avoid problems with redeclared classes, you should delete the other copy of ARC2:
rm -rf ./sites/all/modules/rdfx/vendor/arc/
This code currently doesn't work when it runs inside the profile, so you should run it through devel/php after the profile is finished.
Do have a look at the Configuration section below even if you've used the installation profile, since there are some steps that it can't take care of (notably, configuring ReCAPTCHA).
In order to use the fancy Unicode characters that are produced by recent versions of LaTeXML by default, you'll need to use "utf8mb4" encodings in your MySQL database. Some details are documented on StackExchange. Apart from getting the MySQL settings right, you'll also have to patch your settings.php file AFTER installation and migration.
patch sites/default/settings.php settings.php.patch
The key additional magic configuration for LaTeXML is as follows (run this in the Planetary database after installation):
ALTER TABLE drutexml_cache CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
ALTER TABLE drutexml_cache CHANGE xhtml xhtml longtext CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
If you want to use the pyrdfa module and/or planetmath_versions module, you will also have to patch the core.
patch -p5 < node.module.patch
patch -p5 < node.api.php.patch
(These patches just introduce a new post-save-hook, nothing major!)
Furthermore, you should *doublecheck the value of $base_path and other custom paths and settings in these modules:
sites/all/modules/planetmath_versions/planetmath_versions.module
sites/all/modules/pyrdfa/pyrdfa.module
sites/all/modules/planetmath_view_pdf/planetmath_view_pdf.module
(This will make sure that you're saving backup information in the right place, and also make sure that you're communicating properly with your triple store, putting generated PDFs in the right place...)
Note that we require the xstring.sty extension to LaTeX, which doesn't come in Ubuntu's version of texlive. Unless you've obtained it elsewhere (e.g. from texlive-full), you can install it via
wget http://mirrors.ctan.org/macros/latex/contrib/xstring/xstring.sty
wget http://mirrors.ctan.org/macros/latex/contrib/xstring/xstring.tex
sudo cp xstring.sty xstring.tex /usr/share/texmf-texlive/tex/latex/base/
sudo mktexlsr
And you'll probably want some extra packages, like
apt-get install texlive-fonts-extra texlive-math-extra texlive-pictures texlive-latex-extra
(Note: The last of which will take care of the xstring dependency for you!)
Also: if you're not using the installation profile (which does this for you)... don't forget to set up 16 forums in Drupal to hold the legacy content before importing, or content won't get mapped in properly when you import it!!! (NB. This only applies for PlanetMath clones! If you want to do something else with forums, feel free to skip this step.)
There's another worthwhile patch at http://drupal.org/node/216064 (this prevents form verification from running when all you want to do is delete!).
It's likely helpful to adjust your my.cnf to include
net_buffer_length1000000
max_allowed_packet1000000000
At one time it seemed worthwhile to patch the Userpoints module, but I think that bit is fixed in the module now. If not, you can do this:
patch -p4 < userpoints_nc_revision.module.patch
You should visit admin/config/people/accounts to make sure the settings that apply to new user registration look appropriate for your site's needs. Make sure to turn email rerouting off on production sites via admin/config/development/reroute_email, or people won't get any email.
You'll need to browse to admin/config/content/formats/tex_editor and add "planetmath" as the LaTeXML filter profile. In the future this will be set automatically.
Hopefully this will stabilize soon and the section will go away.
We haven't been able to get this configuration step to work properly within the installation profile, so, once that has run (or once you've configured the other modules to your liking if you're not using the installation profile), you should navigate to devel/php and evaluate the following code. This will allow articles and users to be added to groups, and get group-related permissions set up right.
$og_field og_fields_info(OG_AUDIENCE_FIELD);
$og_field['field']['settings']['target_type'] 'node';
$og_field['instance']['settings']['behaviors']['prepopulate'] array(
'status' > TRUE,
'action' > 'none',
'fallback' > 'none',
'skip_perm' > FALSE,
);
og_create_field(OG_AUDIENCE_FIELD, 'node', 'article', $og_field);
$og_field og_fields_info(OG_AUDIENCE_FIELD);
$og_field['field']['settings']['target_type'] 'node';
$og_field['instance']['settings']['behaviors']['prepopulate'] array(
'status' > TRUE,
'action' > 'none',
'fallback' > 'none',
'skip_perm' > FALSE,
);
og_create_field(OG_AUDIENCE_FIELD, 'user', 'user', $og_field);
og_role_grant_permissions(2, array("create article content",
"update own article content",
"update any article content",
"delete own article content"));
See the section below on "Importing legacy content" for instructions on how to import legacy groups.
You will also have to browse to some Drupal configuration pages and change some settings. The following partial URLs always have to be appended to the URL of your Drupal site.
In order to set up the "legal" page, browse to admin/config/people/legal and insert the TOS. On PlanetMath, these read: For any text you hold the copyright to, by submitting it, you agree to license it under the Creative Commons !Attribution/Share-Alike License 3.0. A copy of the license is included in the section entitled "Creative Commons !Attribution/Share-Alike License". If you import text that you have found elsewhere or that you have co-authored with others, you may only do so if it is available under terms that are compatible with the CC-BY-SA license. Note: it may be advisable to disable this module until after you have completed your migrations, see below (I encountered errors related to this module in my most recent import).
When building a site using real user data, it is important to turn off email notifications during the build process, or you will spam everyone. Accordingly you should configure the reroute_email feature at admin/config/development/reroute_email by supplying an email address to direct all mail to (on a temporary basis).
To set up user score keeping, browse to admin/config/people/userpoints/settings to set some defaults, then override settings for various content types via admin/structure/types/manage (note: we will probably supply our own variant of the Userpoints module soon, presumably this version will have default score set the way we need).
In order for privatemsg to work properly, you will need to visit admin/people/permissions and make sure that authenticated users have permission to "Read private messages" and "Write new private messages" (if users do not have permission to read messages, you won't see links to send them messages!). Similarly, you may want to check admin/config/group/permissions/node/group and subpage(s) to adjust permissions for your group type(s).
The watcher module is configured via admin/config/watcher (e.g. set Article to be a "watchable content type", and check that the email notification settings are to your liking).
The dynamic menus can be configured at admin/config/user-interface/dhtml_menu to suit your tastes.
Follow the instructions here to set up your environment (using Google Mail as the server seems to be the easiest way to go), then install the phpmailer module and configure at admin/config/system/phpmailer.
drush -y dl phpmailer
drush -y en phpmailer
Note: you'll (minimally) want to make sure your database is configured to use UTF-8 by default. See notes above about UTF8MB4
- Walkthrough for UTF8
- Make sure that UTF-8 is used in the database connection, as well
Assuming you've got a Noosphere dump, first run something like this to import it:
mysql> grant all on planetary.* to 'planetary'@localhost identified by 'PLANETARYPASS';
mysql> create database planetary;
$ mysql -u planetary --passwordPLANETARYPASS planetary < pm-db-TIMESTAMP.sql
In order to make content available to migrate, it is necessary to copy the database tables into a place where Drupal can see them (so, you should go through the basic Drupal installation steps above before you continue!). Yes, we could have copied things into the Drupal database directly, but actually, we require a bit of additional massaging, so, for this purpose,
Scripts called tables-into-drupal.sql, tables-into-drupal-pt2.sql and tables-into-drupal-pt3.sql are checked into the repository.
You need to run the first two before you can migrate. First, get the script ready (replace DRUPALDB with the name of your database).
sed -i 's/demodb/DRUPALDB/g' tables-into-drupal.sql
mysql -u root --passwordROOTPASS DRUPALDB < tables-into-drupal.sql
mysql -u root --passwordROOTPASS DRUPALDB < tables-into-drupal-pt2.sql
You should run "part 3" in a similar fashion, but only after you're finished with the migrations (see next section).
mysql -u DRUPALUSER --passwordDRUPALPASS DRUPALDB < tables-into-drupal-pt3.sql
We're using the migrate module, a flexible tool for scripted porting of content.
You must go through the next section on "moving database stuff" below before you can run these migrations!...... once you're done with that, you can run commands like these (if you haven't already)...
drush -y en migrate migrate_ui planetmath_migration
You can then run drush mi --all from the command line.
Alternatively, you can run migrations from admin/content/migrate.
After running these "standard" migrations, there are still a couple non-standard ones that need to be dealt with separately. Make sure you have the relevant modules installed,
drush -y en group_migrate image_migrate
Migrating groups is very straightforward: visit migrate/grp and the groups will be created and populated for you. For images, the relevant data needs to be in place, namely, in ../pm-fileboxes and you should also be sure that the images have a suitable destination:
mkdir sites/default/files/pictures
You should populate things by obtaining a recent "files" dump, unzipping it, and running
mv var/www/noosphere/data/files/objects/ ./pm-fileboxes
cd pm-fileboxes
find -name '*.eps' | xargs -I{} mogrify -format png {}
find -name '*.ps' | xargs -I{} mogrify -format png {}
Make sure that the directories within pm-fileboxes have execute permissions, and the files they contain have read permissions.
Then if you visit migrate/img followed by migrate/nodes the images will be created. You might need to clear the cache first, in order for them to show up! Check the README.txt in the image_migrate module if you run into trouble!
Issues about migrations come up often enough, it's worth additionally checking this page if you run into any trouble.
We've included a script called rebuild.drush that you can use as follows to (re)generate the XHTML and populate your triple store:
./rebuild.drush @SITENAME
Note that there is a bug in this script that requires the following post hoc adjustment on MySQL:
mysql> update node_revision nr set nr.uid (select uid from node n where n.nid nr.nid ) where uid = "";
Currently a couple of the links that we'd like to disable show up in the Navigation menu after the profile runs, even though they are designated as "hidden" in one of our feature (d.o. issue). The way to hide these links is simply to go to admin/structure/menu/manage/navigation and turn them off.
There are some instructions for deleting nodes via PHP on drupal.org.
In MySQL, you can run commands like this:
delete from users where uid > 1;
truncate comment;
truncate field_data_comment_body;
In case of disaster, you can get rid of all the tables:
DROP TABLE ... ;
and rerun
cp sites/default/default.settings.php sites/default/settings.php
chmod a+w sites/default/settings.php
...
In short, going through the process of installing Drupal all over again (see above). Specify the same database name etc., and don't forget to re-enable the modules you want. For a less drastic approach, it may work to try rolling back and wiping migrations from the command line, like so:
drush mr PMObjectComment
drush mw PMObjectComment
...
You can run
mkdir ../Backups/
drush ard all,default --destination=../Backups/mysite.tar
and restore the backups using
drush arr ../Backups/mysite.tar
Make sure you're using the same version of drush on both sides of the connection (do git pull in the respective drush directories). There is a bit of a problem if you don't back up regularly, so back up regularly and save yourself the trouble. Alternatively, load your backup onto some other computer so you can make a new backup from it. Ugh.
This technique can be used to redeploy a site elsewhere. It minimally requires that the database information is the same on the two sites, however it also seems to require the user on the downstream site to have ALL mysql permissions (see this page on drupal.org). Obviously Apache needs to be set up properly on the downstream site, or links won't work (see first section of this page).
Periodically you'll have to run: drush up, which should be enough to update core! To get new versions of the Planetary modules, run git pull origin master. For discussion of additional related issues, see this page.
You will have to run the commands indicated in the section just above and then enable the modules "by hand", with a command as follows. Note that you will also have to hand-configure many of the modules listed here (next section), so we really do recommend using an installation profile instead. However, if you prefer the by-hand method, configuration steps are provided just below.
drush -y en forum migrate migrate_ui views views_ui features \
reroute_email references node_reference user_reference entity \
entity_token og og_context og_field_access og_register og_ui pathauto \
profile2 shadowbox subform token relation relation_dummy_field \
relation_entity_collector relation_select efq_views legal recaptcha \
userpoints userpoints_nc userpoints_nc_revision watcher privatemsg \
pm_email_notify date
To enable the core modules, which will give you a simple working instance of Planetary, you run
drush -y en drutexml mathjax latex_field curli wysiwyg_codemirror
(Note that there is another mathjax module in existence -- but if you want things to work well, don't download that one, and use ours instead!)
If you would like to make your Planetary installation run as a PlanetMath clone, you should additionally run
drush -y en planetmath_migration image_migrate group_migrate article_setup \
correction problem solution review question collection pyrdfa msc_browser \
planetmath_blocks planetmath_edit_article planetmath_image \
planetmath_migration planetmath_migration_extras \
planetmath_og planetmath_og_attach planetmath_og_display \
planetmath_orphanage planetmath_owner planetmath_user
to install the relevant custom modules (this will introduce some non-Drupal dependencies, see below).
(Note: A full list of the modules that ship with Planetary is available at PlanetaryModules -- there are quite a few more configuration options, so check out the list.)
The PlanetMath profile takes care of this, but if you're not using it, here are some steps to follow. Do this promptly, otherwise you'll have a bunch of spam accounts on your site right away!
To configure (Re)Captcha, first download it if you haven't already.
drush dl captcha-7.x-1.x-dev
drush dl recaptcha
drush -y en recaptcha
Then visit admin/config/people/captcha and select !ReCaptcha as the default Captcha type, then visit admin/config/people/captcha/recaptcha to enter your site keys. Alternatively, you can download and configure "math captcha" or "riddler" (recommended!)
drush dl captcha_pack
drush -y en math_captcha
drush dl riddler
drush -y en riddler
Yet another interesting spam solution is the BOTCHA, see the [http://drupal.org/project/botcha project page] (note: requires javascript, but most people have that these days).
-
admin/config/content/formats/add(create a LaTeX filter enabled content type; name it something like "TeX Editor") -
admin/config/content/wysiwyg/(select !CodeMirror as the TeX Editor modality) -
admin/config/content/wysiwyg/profile/tex_editor/edit(check the stex button under “Buttons and Plugins”) -
admin/structure/types/manage/article/fields(If you haven't used the article_setup module, which does this for you, add a LaTeX field to your article content type.) - You should also go to
admin/structure/types/manage/article/fields/field_latexand select TeX Editor as the "Filter to be used" (and "Text Format", in the little demonstration that comes up). - In the LaTeX filter tab of "Filter Settings" on
admin/config/content/formats/tex_editor, you can specify a LaTeXML daemon URL, if you want something other than the default (e.g. if you RunYourOwnDaemon).