DEPRECATION WARNING

This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.

EXT: Staging¶

Author:	Kasper Skårhøj
Created:	2002-11-01T00:32:00
Changed by:	Susanne Moog
Changed:	2009-04-08T13:53:38
Classification:	neustastaging
Description:	Manual for the neustastaging Extension
Keywords:	forAdmins, forDevelopers, forAdvanced, workspaces, staging, versioning
Author:	Susanne Moog
Email:	s.moog@neusta.de
Info 4:
Language:	en

EXT: Staging - neustastaging

EXT: Staging¶

Extension Key: neustastaging

Language: en

Keywords: forAdmins, forDevelopers, forAdvanced, workspaces, staging, versioning

This document is published under the Open Content License

available from http://www.opencontent.org/opl.shtml

The content of this document is related to TYPO3

- a GNU/GPL CMS/Framework available from www.typo3.org

Table of Contents¶

EXT: Staging 1

`Introduction 3 <#1.1.Introduction|outline>`_

What does it do? 3

Screenshots 3

`Users manual 4 <#1.2.Users%20manual|outline>`_

Staging Pages 4

Staging Files 4

Check staging status 4

`Administration 5 <#1.3.Administration|outline>`_

Dependencies 5

`Configuration 6 <#1.4.Configuration|outline>`_

Reference (config.inc.php) 6

Examples 8

`Known problems 11 <#1.5.Known%20problems|outline>`_

`To-Do list 12 <#1.6.To-Do%20list|outline>`_

`ChangeLog 13 <#1.7.ChangeLog|outline>`_

Introduction¶

What does it do?¶

If you have a multiple server environment with single servers for testing, inserting content and production use the normal TYPO3 workspaces are not sufficient anymore. This extension enables you to easily work with multiple servers. It adds multiple backend modules for preparing pages and files to be staged to another server by a cronjob. It also contains a basic version of the cronjob which is able to stage the tt_content and pages table as well as files in fileadmin.

Screenshots¶

The staging module for pages.

The staging module for files. Bold printed files are not yet staged.

Users manual¶

Staging Pages¶

The staging is very easy for a user:

Click on the module “Page Staging” in the left menu.
Choose a page to stage.
Check whether you want to stage the subpages, too. Pay attention, as all subpages will be selected recursively, so if you stage your root page and activate this checkbox you will publish your whole website.
In the next step the pages to be staged are shown. Check whether your selection is correct and press “Submit”.

Staging deleted pages¶

As you can't select a deleted page in the page tree to be submitted you have to use a small trick. Select the parent page and activate the “Include subpages” checkbox. You will see that even deleted pages are shown in the list of pages to be submitted. If you submit this selection the deleted flag will be staged with the page so it is deleted in the next stage, too.

Staging Files¶

The staging of files is very similar to the staging of pages:

Click on the module “File Staging” in the left menu.
Choose the files or folders to stage.
Check your selection in the next step. If all is well click on submit.

Check staging status¶

You can check the status of your staged files and pages in the module “Staging Log” in the help section of the main menu.

Non-admins see only their own submissions whereas admin users see the submissions of everyone so they can trace which user is responsible for which change and so prevent errors and miscommunication.

Administration¶

You only have to install the extension on your first stage server.

Download the extension from the extension repository.
Install the extension and let it add the required new db-fields and tables as well as resolve the dependencies.
TYPO3wise all is ready now, next configure the cronjob and the staging script (see section Configuration)

Dependencies¶

This extension depends on em_filereferences. Em_filereferences replaces the normal TYPO3 media field with a new one that doesn't create copies in upload. As this extension has currently no way of connecting content elements to files the users have to publish the files in fileadmin manually. TYPO3s normal way of copying things in uploads/ must be prohibited, as it breaks the staging process.

You can probably use any other extension that prevents TYPO3 from creating those copies, like DAM, but those are not tested. Please report if you try other combinations. (To try you have to change the file “ext_emconf.php”→dependencies)

Configuration¶

You need:
- 2 servers (both with a TYPO3 installation of the same version with the same extensions installed)
- 1 server which will act as script server (can be any of the 2 above, if you want to secure your production system you should use your testing and editing server) → this server needs to be able to access the filesystems and databases of both servers and execute cronjobs
Make sure both servers have the exact same environments and data when you install this extension.
Configure your databases and tables in the file “config.inc.php” (see syntax and example below – it is preconfigured for tt_content and pages)
Configure a cronjob to execute the file “staging.php” every 5 minutes (more or less depending on your needs).
If you want to run the staging script on a separate server or in a separate location you can just copy the whole “scripts” directory. Everything you need is in there.

Reference (config.inc.php)¶

Property

level

Data type

int

Description

Error level to be reported:

1 = Error

2 = Warning

3 = Error & Warning

4 = Notice

5 = Error & Notice

6 = Warning & Notice

7 = Error & Warning & Notice

Default

3

fileName¶

Property

fileName

Data type

string

Description

Name of the logging file

Default

path¶

Property

path

Data type

string

Description

Path to log file

(for example: /var/logs/staging/)

The default is the logs directory relative to the logging script.

Default

logs/

mail¶

Property

mail

Data type

array

Description

Configuration for log mails

Default

[neustastaging:(LOG).array(logtype[default|staging])]

level¶

Property

level

Data type

int

Description

Error level to be reported:

1 = Error

2 = Warning

3 = Error & Warning

4 = Notice

5 = Error & Notice

6 = Warning & Notice

7 = Error & Warning & Notice

Default

3

subject¶

Property

subject

Data type

string

Description

Subject of the log mails

Default

STAGING-LOGS

sndMail¶

Property

sndMail

Data type

string

Description

Sender email address

Default

rcvMail¶

Property

rcvMail

Data type

string

Description

Receiver email address

Default

sndName¶

Property

sndName

Data type

string

Description

Sender name

Default

STAGING

rcvName¶

Property

rcvName

fileTable

Data type

array

Description

The table configuration for the table that holds the infos about the files that shall be staged – just leave as is.

Default

cacheTables¶

Property

cacheTables

Data type

array

Description

The tables where the caching data is stored. If you stage a page the corresponding cache entries are deleted.

Default

rootTable¶

Property

rootTable

Data type

array

Description

The main table from which all other relations are derived. In TYPO3 this is the pages table.

Default

[neustastaging:(STAGING).array(type[db])]

Property

whereField

Data type

string

Description

Field for the “where” clause. On first level this is the marker for the field that contains the info whether the page should be staged or not (“tx_neustastaging_staging”), on all other levels (in “extTables”-Array) it marks the “foreign key” field of the table (in TYPO3 mostly “pid” if the rootTable is set to “pages”)

Default

1 ^st Lvl: tx_neustastaging_staging

2 ^nd Lvl:

pid

pathField¶

Property

pathField

Data type

String (only “fileTable”)

Description

In the fileTable array you have to enter the name of the field that holds the path to the files that shall be staged in the next step. You don't need to change this if you did not change the extension.

Default

path

extTables¶

Property

extTables

Data type

array

Description

Array for dependent tables. The dependent tables are stored in an indicated array. The possible configuration options are the same as for the root table.

Example:

'extTables' => array (
                   0 => array (
                           'name' => 'sys_template',
                           'title' => 'title',
                           'uidField' => 'uid',
                           'whereField' => 'pid'
                   ),
                   1 => array (
                           'name' => 'tt_content',
                           'title' => 'header',
                           'uidField' => 'uid',
                           'whereField' => 'pid'
                   )
           )

Default

[neustastaging:(STAGING).array(type[db]).array(table[fileTable|cacheT ables|rootTable])]

rsyncBin¶

Property

rsyncBin

Data type

string

Description

Path to rsyncBin. Normally just “rsync”.

Default

rsync

rsyncParams¶

Property

rsyncParams

Data type

string

Description

Rsync parameters. You should not need to change these.

Default

avR --delete -e ssh

Property

rootPath

Data type

string

Description

This is the name of the fileadmin directory (the same as the last part of the previous option). If you have nothing strange configured, you should leave it as “fileadmin”.

Default

/fileadmin/

[neustastaging:(STAGING).array(type[fs]).array(type[srcFS])]

sshPrefix¶

Property

sshPrefix

Data type

string

Description

This is the sshPrefix for the connection to the second server (used for rSync).

Default

user@server

rootPath¶

Property

rootPath

Data type

string

Description

This is the full path to the fileadmin directory of the destination installation.

Default

[neustastaging:(STAGING).array(type[fs]).array(type[dstFS]).[indicated Array]]

Examples¶

Full configuration example:¶

$GLOBALS['DB'] = array(

       'sourceDbIdentifier' => array (
            'host' => 'db-host',
            'user' => 'db-user',
            'pass' => 'db-pass',
            'db' => 'db'
    ),
    'destinationDbIdentifier' => array (
            'host' => 'db-host',
            'user' => 'db-user',
            'pass' => 'db-pass',
            'db' => 'db'
    )
);

$GLOBALS['LOG'] = array(
    'default' => array (
            'level' => 3,
            'fileName' => 'gen',
            'path' => '',
            'mail' => array (
                    'level' => 3,
                    'subject' => 'DEFAULT-LOGS',
                    'sndMail' => 'errors@example.com',
                    'rcvMail' => 'errors@example.com',
                    'sndName' => 'DEFAULT',
                    'rcvName' => 'DEFAULT'
            )
    ),
    'staging' => array (
            'fileName' => 'staging',
            'mail' => array (
                    'level' => 3,
                    'subject' => 'STAGING-LOGS',
                    'sndMail' => 'errors@example.com',
                    'rcvMail' => 'errors@example.com',
                    'sndName' => 'STAGING',
                    'rcvName' => 'STAGING'
            )
    )
);

$GLOBALS['LOCK'] = array (
    'default' => array (
            'maxAge' => 1800,
            'fileName' => 'lock'
    ),
    'staging' => array(
            'maxAge' => 3600
    )
);

/*********************************************************
 * STAGING CONFIGS
 */
$GLOBALS['STAGING'] = array (
    'db' => array (
            'fileTable'     => array (
                    'name' => 'tx_neustastaging_files',
                    'title' => 'path',
                    'uidField' => 'uid',
                    'pathField' => 'path',
                    'whereField' => 'thread_prio'
            ),
            'cacheTables' => array (
                    0 => array (
                            'name' => 'cache_pages',
                            'whereField' => 'page_id'
                    ),
                    1 => array (
                            'name' => 'cache_pagesection',
                            'whereField' => 'page_id'
                    )
            ),
            'rootTable' => array (
                    'name' => 'pages',
                    'title' => 'title',
                    'uidField' => 'uid',
                    'whereField' => 'tx_neustastaging_staging',
                    'extTables' => array (
                            0 => array (
                                    'name' => 'sys_template',
                                    'title' => 'title',
                                    'uidField' => 'uid',
                                    'whereField' => 'pid'
                            ),
                            1 => array (
                                    'name' => 'tt_content',
                                    'title' => 'header',
                                    'uidField' => 'uid',
                                    'whereField' => 'pid'
                            )
                    )
            )
    ),
    'fs' => array (
            'rsyncBin' => 'rsync',
            'rsyncParams' => 'avR --delete -e ssh',
            'srcFS' => array (
                    'mountPoint' => '/path/to/fileadmin/',
                    'rootPath' => '/fileadmin/'
            ),
            'dstFS' => array (
                    0 => array (
                            'sshPrefix' => 'user@server',
                            'rootPath' => '/path/to/destination/fileadmin/'
                    )
            )
    )
);

Configuring MM-relations¶

For the staging of mm-related tables use the following snippet to configure the dependent fields:

1 => array (
        'name' => 'tt_content',
        'title' => 'header',
        'uidField' => 'uid',
        'whereField' => 'pid',
        'extTables' => array (
                0 => array (
                        'name' => 'tt_content_tx_myextension_data_mm',
                        'title' => '',
                        'uidField' => 'uid_foreign',
                        'whereField' => 'uid_local'
                )
        )
),

Known problems¶

Works so far only in combination with em_filereferences
Images/Files for content elements have to be published before the (db) content is published (or – if not in this order – the cache on the second stage has to be cleared.

To-Do list¶

Finding a way to use the extension without em_filereferences
Publishing the files belonging to content elements automatically

ChangeLog¶

0.1.0 Initial release

13