Gallery2:Multisite - Gallery Codex
Personal tools

Gallery2:Multisite

From Gallery Codex

Introduction

Multisite is an installation option of G2 to save diskspace and administrative work when installing and upgrading multiple independent G2 installs on the same webserver. Independent means that the multisite G2 installs don't share albums, photos, users, or anything else. They all use their own database and their own storage directory.

Terms

codebase - The codebase is the directory with the gallery2 installation files which is several megabytes in size. Only a single codebase is required for an arbitrary number of multisite installations. The codebase must be accessible from the internet. The codebase serves as the central place to install all the multisite installations. If you want to install a new multisite G2, browse to the codebase, run the installer, and choose multisite in the multisite step of the installer.

multisite - A multisite installation is a lightweight G2 installation which depends on the single codebase. A multisite has only 6(7) files (main.php, index.php, embed.php, upgrade/index.php, lib/support/index.php + config.php (, .htaccess)).

A G2 multisite setup has a single codebase installation and an unlimited number of multisites.

Advantages

  • The primary advantage of multisites over normal G2 installations is saving the disk space that is required for each gallery2 folder (50-100 MB depending on the cluster size of the HDD partition). Only a single real gallery2 folder is required (codebase), multisites only use a few kilobytes per installation (plus the photos that they contain).
  • You only have to upgrade a single codebase. Once the codebase is replaced with a new G2 version, just visit the multisites and each multisite will automatically start it's upgrade process. Each multisite has to be upgraded independently, but you have to replace the underlying codebase only once.
  • The multisite installations don't share users, album/photos, or anything else from the user's point of view. Multisites are completely separate and share only the same codebase.

Also, compare multisite to the multiroot module.

Disadvantages

  • Sensitive downloadable plugin maintenance - If an admin of one multisite upgrades a plugin (module, theme) via downloadable plugins, the admins of the other sites have to upgrade the plugin as well.
  • All multisites share the same set of plugins (modules and themes). If you create a custom theme for one site, all other sites can use it as well.
  • No option to use local .tpl overrides in multisites. (Clone the whole theme instead to change templates.)
  • Versions before G2.2 did not have a lib/support/ folder in multisite folders (can easily be added).
  • No mod_rewrite auto-detection - The URL rewrite module can't test itself during the configuration of the module.

Initial Setup - Install the codebase

Before an arbitrary number of multisite G2 installations can be installed, you need to get the gallery2 application and put it on the webserver. This will be the codebase.

The codebase folder ("gallery2" by default) needs to be accessible from the web. The codebase serves all static content (theme.css files, the small icons, the gallery logo, ...) for all multisites. Therefore, it's not sufficient if the codebase is only accessible from the local network, it must be accessible from the web.

Example: You extract the gallery2 application in a folder such that it, the installer is accessible with the URL http://www.example.com/gallery2/install/. The corresponding filesystem path could be something like /var/www/example.com/public_html/gallery2/

How to install a new multisite

Once the codebase is on the webserver and accessible from the web, one can install an unlimited number of multisite installations. The codebase installer serves as the central installation utility for all new multisites.

1. Browse to the codebase

You want to install a new multisite, whose URL will be http://www.example.com/gallery2/

To start the install process for a new multisite, browse to the codebase installation with a web browser and enter the installer, e.g. browse to http://www.example.com/gallery2/install/.

2. System Checks Step

Pay attention to any settings recommended by the installer, particular the first time using the installer. These settings should apply to the codebase and all multisites. If you make the changes (such as increasing the PHP memory limit) in a .htaccess file in the codebase directory then the installer will report "Pass" even though the setting may not apply to the multisite you are about to install.

3. Multisite Step

In the step for installation type, select the multisite option and enter the filesystem path of the new G2 multisite installation. e.g. /var/www/www.example.com/public_html/ .

The installer needs to create four files (index.php, main.php, embed.php, upgrade/index.php) in this multisite directory. Thus you have two options:

  • change the filesystem permissions of the multisite directory such that the webserver has read, write, and execute permissions (chmod 777), or
  • create four empty files with the correct name yourself and chmod these four files 666.

There is also an optional fifth file, lib/support/index.php. The installer will write this file only if possible (if dir is 777 it is always possible; creating files yourself you can choose whether or not to add this one).

Once the installer knows the multisite directory and has write permissions for the files, you can click "Select Directory" to continue. The installer will then generate some code and paste it in the the files such that the multisite knows where the codebase files are.

If you're finished with this step, you can change the filesystem permissions of the files and the multisite directory back to 755 (user has read, write, execute, group and world have read and execute permissions).

WARNING: The files (index.php, main.php, embed.php, upgrade/index.php, lib/support/index.php) in the multisite directory are not the same as the ones with the same name in your codebase. They are much smaller and if you exchange the files with the ones from the codebase, it won't work.

WARNING: Do NOT enter your codebase directory as multisite directory. It would replace the files in the codebase with the much smaller multisite versions of those files and thus, G2 won't work anymore. If you accidentally made that mistake, just replace those files in your codebase again with the ones from the gallery2 application files that you have downloaded.

4. Storage Setup Step

In the storage setup step, choose a new g2data directory for each multisite. Each multisite needs its own storage directory. In our example, it could be /var/www/e-photos.com/g2data/ .

WARNING: Do NOT choose a storage directory of an existing and running G2 (multisite) installation. If you choose the same storage directory for multiple (multisite) installations, it will destroy the existing other installation.

5. Database Setup Step

In the database setup step, choose a new database (or a new table prefix) for each multisite. Each multisite installation needs its own database tables.

WARNING: Do NOT choose the same database configuration for multiple G2 installs. If you choose the same database + table prefix for multiple (multisite) installations, it will destroy the existing installation.


If you have shell access to mysql, log into mysql as the database root user, and then you can probably create a new mysql database with the following command(s):

CREATE DATABASE dbname; GRANT ALL ON dbname.* TO username@'localhost' IDENTIFIED BY 'password'; FLUSH PRIVILEGES;

Obviously replace dbname, username, and password with the appropriate values.

6. Finish the Remaining Installation Steps

Finish the installation process by completing the remaining installation steps.

How to Upgrade a Multisite

Backup early and backup often. And certainly backup before you upgrade.

1. Update the Codebase

Follow the normal upgrade instructions to upgrade your codebase (the gallery2/ folder) files.

Note: You don't need to run the upgrade wizard for the codebase. You just need to replace the application files (the gallery2/ folder) with the latest release.

In short: Get the latest code, upload it to the webserver, and unpack it over your existing codebase (or use svn instead to update the code).

Changing Codebase Directory For some it might be desirable to upgrade multisite instances one-by-one against a second codebase. This upgrade approach reduces downtime for other multisite instances. To upgrade against a separate codebase you must edit the galleryBaseUrl value in the multisite's config.php and the edit require paths in embed.php, index.php, main.php, and upgrade/index.php to point to the newer codebase.

WARNING: If you use a PHP accelerator / cache (e.g. Turk mmCache, Ioncube PHPA, eaccelerator, Zend Studio, etc.), flush (clear) the cache of the accelerator. Omitting this step can sometimes lead to errors during and after the upgrade process.

2. Upgrade each Multisite

Once the codebase was replaced with the new application files, the upgrade process will start automatically when you browse to one of the multisite installations. You will need to run through the upgrade process for each multisite separately.

  • 1. Make a backup of your data (g2data folder and the database) when it tells you to!
  • 2. Browse to the upgrader and follow the instructions there.
  • 3. Enjoy your new version of Gallery 2.

Scenarios

Internet Service Provider (ISP)

An ISP offers G2 to its customers. Each customer has their own domain / home:

Note: The codebase does not have to run a live gallery2 application. In this case, it only serves as a central repository for the application files, as the central installation tool, and it serves the static content for the multisites.

G2 Hosting for Friends

You decide to host G2 installations for your friends on your domain:

Note: Either use different databases for each multisite or use different table prefix. In the end, each multisite needs their own database tables.

Note: In this case, the codebase is also used as a G2 installation. Unlike the multisites, the codebase is an ordinary G2 installation, which just happens to also serve as the installation tool for multisite installations on the same webserver.

Administration and Maintenance

Plugin Management

  • All multisites share the same set of modules and themes (plugins).
  • To allow multisite admins to install (transfer / copy) new plugins on the server, change the permissions of the modules/ and themes/ folder of the codebase such that the webserver can write to these folders.
  • To allow multisite admins to upgrade existing plugins to newer versions, make all files and folders in modules/ and themes/ writeable for the webserver.
  • To block multisite admins from adding new plugins or upgrading existing plugins, ensure that the modules/ and themes/ folder are not writeable.
  • Mutlisite admins can go to Site Admin -> Plugins and Site Admin -> Plugins -> Get More Plugins just like admins of a normal installation.
  • The only difference is that multisite admins can never delete a plugin. They are only allowed to install, uninstall, activate, deactivate, and configure plugins.

How to change a standalone G2 into a multisite

Original source of these instructions: http://galleryproject.org/node/35733#comment-130428

Only if you really want to separate your existing g2 from the codebase, i.e. either move the codebase to another directory or move the existing installation to a new directory, only then you need to follow the next steps.

  • Database:
    • Of course you can keep your existing database etc.
  • URL rewrite module (short urls):
    • If you use the url rewrite module, deactivate it before you begin with the changes. and delete the existing .htaccess file. You can install / activate the module again once you're finished with the process.
  • Storage directory (g2data):
    • If you want to move the g2data dir into another folder, do it as the first step. Then make sure the permissions for the g2data folder and all its subdirectories and files are still ok (chmod -R 777 g2data or chown -R webserveruser g2data).

A) Keep installation in the folder where it is, but move the gallery2 files away to a more general directory:

  1. copy config.php to another folder, just such that you don't forget / lose your database connection information.
  2. Move the gallery2 directory to its new place. If you had the g2data directory within the gallery2 directory, a) don't move it with the gallery2 directory and b) consider having it above the webroot for your future installation (only then the image firewall of G2 works (security)). Make sure the directory where your installation used to be is now empty.
  3. Browse to the address of the new home of your gallery2 directory and start the installer gallery2/install/index.php).
  4. In the installation type step, choose multisite and enter the filesystem path to the directory where G2 used to be. Create a new (empty) gallery2 directory if needed. chmod 777 etc. as if it was a normal multisite installation.
  5. In the storage directory step, enter the path to your existing g2data directory. I assume it's already where it should be (as instructed in the prepation for these steps).
  6. In the database setup step, enter the same old database connection information. If you forgot it, take a look at your backup copy of config.php. Click save.
    • It should show 3 options: erase, save and "reuse existing database tables". Choose the "Reuse" option!
  7. In the Admin user step, click save
  8. In the config file step, it should say, that it created the config file successfully.
  9. You can stop the installation process at this point. Your multisite should work at this point


B) Keep the codebase in the folder where it is, but move the existing installation into a new directory:

  1. Most of the following procedure is exactly like a normal multisite installation. Your codebase is already where it is, because your existing gallery2 is exactly like a codebase.
  2. Browse with your webbrowser to your gallery2/install/index.php page
  3. In the installation type step, choose multisite and choose the filesystem path of the new home for your existing gallery2 installation. Create the directory if necessary and chmod it correctly. Advance to the next step.
  4. In the storage setup step, enter the correct path to the existing g2data directory, advance to the next step.
  5. In the database setup step, enter the database connection information for your existing g2 database. Hit save, hit "Reuse database tables".
  6. In the admin user setup step, hit save.
  7. In the create config file step, it should say that it successfully created a config file.
  8. At this point, you can stop the installation process, your multisite should be running.
  9. Delete the config.php and the .htaccess file (if it exists) in your codebase directory (don't delete these files in your new multisite directory).

How to change a Multisite Gallery into a Standalone

This is pretty straight forward.

  1. Make a backup (i.e. copy it to your computer) of the config.php that is in your multisite gallery/ folder
  2. If there is a .htaccess file in your multisite gallery/ folder (hidden in FTP clients unless you make it show hidden files), make a backup of it as well
  3. If the storage folder of your multisite is within the gallery/ folder of the multisite, move it away, e.g. to the folder above the gallery/ folder
  4. Now you can delete your multisite gallery/ folder
  5. Copy the codebase gallery2/ folder to the place where your multisite gallery/ folder was
  6. Copy your backup of the config.php (and .htaccess) into the new gallery/ folder
  7. Edit config.php: Find the line $gallery->setConfig('galleryBaseUrl', ...); (not to confuse with 'baseUri') and change the part after the comma to '' (i.e. $gallery->setConfig('galleryBaseUrl', '');). Save config.php and put it into your multisite gallery/ folder.
  8. Move the multisite g2data/ back to where it was if you had to move it away as instructed earlier.
  9. Done. Your multisite is now a standalone Gallery. If there are no other multisites, you can also delete the codebase gallery2/ folder.
  • If there are filesystem permission problems when trying to delete the old multisite folder and the files in there, try to chmod the files 777 first. If everything else fails, please ask your webhost to remove the folder for you. Also see: Tool to chmod within Gallery (not available for mulitisites that have been installed before Gallery 2.2)

Gallery MultiSite setup and migration/upgrading.

If you have an existing Gallery 1 photo album the first thing to do is to make sure your existing Gallery site has been updated to the last G1 version. http://sourceforge.net/project/showfiles.php?group_id=7130&package_id=7239&release_id=358363

  1. Backup your gallery albums.
  2. Download the backup if you have not downloaded it already.
  3. Run the find orphans script on your albums. Fix any problems that it found.
  4. Rename your gallery folder to "g1".
  5. Go to your new g1 location and edit your config.php so that your gallery will work in the new location. (IE change the old location folder name to the new g1 folder name)
  6. Visit every album in your g1 album at least once to make sure it is working correctly. Fix any problems if not.

Next thing to do is to setup a Gallery 2 "Standard installation" to act as the main code base for all of your galleries. The instructions are simple and straight forward as the installer does it for you in Gallery 2.

Note that if this installation isn't going to be used for a gallery itself do not install any of the modules. See step 9 below for reason. Once you have a main code base installed be sure to test it by at least creating a single album containing at least 1 photo viewable online. If all is well continue.

Once this is done return the the G2 installer page and rerun it.

IE: your_domain/html/gallery2/install/

At step 3 choose Multisite type and then:

1.) Insert the path to your new gallery. This can be anywhere publicly viewable on the same server.

IE: another_domain/html/gallery

2.) Before you hit next make sure this gallery folder exist and the its permissons are set to 777.

mkdir another_domain/html/gallery
chmod 777 another_domain/html/gallery

3.) Go ahead and create the "g2data" folder outside the publicly viewable html folder. in this case it would be 'another_domain/g2data'. Make sure to chmod this to 777 also.

mkdir another_domain/g2data
chmod 777 another_domain/g2data

4.) Hit next on the Installer and input the path to the g2data folder you just created and hit next.
5.) In this 5th step of the installer you will input your database connection info.

A note on this. If you're upgrading from Gallery 1.5.1 you will need to create a database
for Gallery 2 to use. So do this now if needed. 
If you're using Gallery 2 already BACK IT UP!


Note: You can have more than one gallery use the same DB. If you do this, you must change the table prefix to avoid conflict.

IE for 'your_domain' you could put 
"Table Prefix: g2_your_domain_
 and then for 'another_domain' you would put 
"Table Prefix: g2_another_domain_

6-8.) These are simple so just read the on screen instructions.
9.) Select the modules you want installed.

Note that these are independent of the main installation so must be reinstalled for 
this new "sub" installation. These can be installed, uninstalled, activated, and
deactivated later from the gallery admin pages.

10-11.) Are simple so follow and you're finished.

To finish the UPGRADE portion.
Go to your new gallery page.
Log in as admin.
Go to the Import page with link on left hand side. If you do not see this link go to the Modules Control and install and activate this module.
It will ask for the path of your old albums. It will check this path and if AOK will ask you what you want to import from it.

Note that if you have large albums import might fail especially when creating thumbnails    
due to the memory limits. At least trying to build all my thumbnails in import and through
maintainence fails because of this. It's not a big deal because the first time any  
picture is viewed a thumbnail will be built then.

Import pictures and you're done.
Check to make sure your pictures have uploaded. Once you're satisfied all is well you can remove your old g1 from your server. Don't sweat it as you already have the albums backed up remember!

Enjoy!

.: Flipc

Missing Features

Certain features are still missing...

  • Installation script to automate the installation process. e.g. a Command line interface PHP script that accepts arguments like multisite directory path, storage directory path, the database configuration, and a list of modules to install.
  • Central upgrade process / script / manager to upgrade multiple / all multisites at once.
    • Note: You can already upgrade multisites like any other G2. But it would be nicer, if you could click on a single link / run a single script and upgrade your 100 multisites at once, wouldn't it? :)
  • URL Rewrite cannot test if mod_rewrite works for a multisite location due to the fact that there's no files which the test relies on. You may take your chances and activate this module anyway, but if you experience any problems with bad URLs you should deactivate URL Rewrite. There's no guarantee that if the test passes for your codebase version that mod_rewrite also works for your multisite.