⌘ Styx - Installation

Get Styx - ‘install’ or ‘upgrade’

The important migration Upgrade HowTo - Step by Step Guide:

Preamble: (If not using Styx already, and having done that before...)

Migration of very old Serendipity S9y-Origin installations

Please note: The more Serendipity Styx develops and time passes by, the more it differs from the origin, since the ongoing development has already more than doubled the commit changes against S9y Origin! The normal version upgrade manager until Styx 2.9.5 includes all tasks which are necessary to successful proceed between the two editions. With Serendipity S9y-Origin 2.1 + releases there were no migration routine(s) checked. This does not say they could not work too. It is just a matter of having upgrade tasks matching and taking the responsibility, so you don't destroy certain parts of your system.

The following Guide was originally meant to help migrating this "Origin-to-Styx" process to the first Styx release 2.1.0, over to 2.2, 2.3 and then 2.4.0. In a second step this was reworked for Serendipity Styx 2.6, better pointing you back to 2.4 for the autoupdater plugin. By time, Serendipity Styx stable hit version 2.9.5, it was checked again. The 2.9(.5) revision branch is the recommended last version for simple drop-over migration upgraders! Do not do this Origin-to-Styx migrations with Styx 3.x releases, since a lot of helper tasks were removed! That said, if you are on Styx already, jumping to Styx 3.x will be as easy as ever.

Styx has come a long way with lots of changes. It would require to inspect and update this guide in deep to jump to latest release without any possible flaws for these migration upgrades. Needless to say: Best of all is a complete new installation.

Starting from scratch enables "hand-cared migrations " too, since you always install the latest Styx release independently, make it run and afterwards carefully include everything you (also) had in your old Blog, like plugins (by their new edition), your MediaLibrary uploads/ items and probably more you had a need to store in other places. Then export your old database (probably as UTF-8), edit the SQL file with an UTF-8 ready Editor like Notepad++ and then carefully fill up the new database tables one by one to include all necessary parts of your old install. It has successfully been done by users before! But you need a little knowledge which database items have dependencies in other database tables and which database parts and values can get ignored. This enables to have a clean system with clean structure and including your blogs history.

But now, back to the migration guide:

Upgrade migration by named package (FTP or WGET like tools)

Did I already say: Back it up? No? Then fully backup your blog and your database!

Get Styx 2.9.5 (‘serendipity-2.9.5.zip’) and deflate it. It will unzip to a "serendipity/" directory (Note, that GitHub source zips are DEV versions and have another parent directory).

  • PREPARATIONS:
  • First of all, hide your normal blog site from the public by using a simple .htaccess restriction! (see about locking here.)
  • Second, log-in to your old blog and remove all Plugins that you don't essentially need! You most probably have very old versions lying around, which are prone to error (in example, the "browser compatibility event plugin").
    If you are not able to access your old blog because of too new PHP versions and regarding fatal errors, you have to do this step by hand.
  • Third, update the Plugins of essential need by deleting their directories and replacing them with a fresh version from Styx additional_plugins. Do not just drop it over the old!
  • Fourth, check into templates and make sure you have a default theme installed. There is no best of use case, since that depends on the version you have. Beside of this "Bulletproof", or better "default", or the newer "2k11" is recommended at this point. Why is this necessary? Themes have changed a lot. Some even may carry old smarty API calls (same as in plugins), which then would fully halt your system on the upgrade. We want to avoid this as much we can.
  • THE UPGRADE:
  • Perform the fetch of the new Styx package as said on start. Copy all inner unzipped content to your current installation. Point yourself to the blogs http page. The upgrade manager should start and give you some upgrade task informations of what is going to happen and what you might have to do later on (like, update your copy or child themes, etc.). If you don't get any errors while processing this upgrade step, you are happy, but it does not mean there are no possible hidden flaws that can hit you later. Follow the upgrade until finished.
  • If you do get any fatal errors which halt your system, you have to search for their reason and fix them up. Most common errors are old left over plugins, yelling a Smarty Exception error in the Smarty package (files). This is not helpful, since you probably don't get to know which is the one. Now you have to try your best and guess! Disable or remove one by one and check your upgrade page on each if the error is gone. If you have errors that specifically point to a plugin, replace it with a fresh version like done before for the essentials.
  • POST UPGRADE CHECKS:
  • Log-in. Check your Browser to load a fresh copy of internal assets by [Ctrl-F5] or whatever command your Browser needs to reload its cache. Immediately check into Plugins and perform a Plugin update run. After that you might need to reload your Browsers Cache again.
  • Check into Maintenance section. Check for "Plugin Cleanup Manager" and perform a local plugin zombie check. Remove any shown plugins in which you are not personally involved as a developer. Now do the same with "Theme Cleanup Manager".
  • All is neat and looks ok? Great! Now, open up PhpMyAdmin or your Terminal and do pull another full database backup.
  • Perform a database UTF8MB4 migration in the Maintenance "Database: UTF-8-MB4 migration" section. If this is possible on your system, you have a examine and probably a perform button showing up. Read the info notes about what is going to happen. Follow the migration and migration guide as long as it is necessary. At the end you get a green OK message telling you a success "UTF-8-MB4 charset".
  • Now you are ready to chill back and have a fresh look around. But there is more to do for you. You still have to care about personal themes (remember what the upgrade tasks were talking about). And you need some backend finetuning by option changes/tweaks:
  • Read on in the following: "The hitchhikers guide to Upgraders Styx Backend tuning".

Steps for using an autoupgrade with the autoupdate Plugin.

  • If you are still with Serendipity 1.6 or 1.7 Series, please follow this guides points “a” to “c”.
  • Then manually append this line to your backend startpage URL: 
    ?serendipity[adminModule]=event_display&serendipity[adminAction]=update&serendipity[newVersion]=2.4.0
    (as a 1-liner) and hit ENTER - This will start the autoupdate upgrade routine. You are now at the 2cd half of upgrade guide point “f”. The new version string, ie. ‘2.4.0’, has to match the zip files version string, ie. ‘serendipity-2.4.0.zip’, which also has to match the searched docs/RELEASE file version string!
  • Afterwards resume with point “g” to “h”! Enable “d” at last.
  • On the other hand, if you upgrade an existing Serendipity 2.1.x installation, it makes sense to downgrade your version first to ‘2.0.0’ in the serendipity_config.inc.php and in the serendipity_config_local.inc.php files, to get all the recommended and necessary upgrade tasks in need for Styx on upgrade (see a-h steps).

Read and follow carefully (inclusive the advising “Update” section):

  1. Manually update the Serendipity Spartacus plugin file with the temporary ‘styx-spartacus-up’ file (4) to solve some bugs and set the custom plugin load location option to this URL (5).
  2. Update the “Autoupdater” by Spartacus from the new location, currently this is version 1.5.3 or up.
  3. Click somewhere else and then return to the plugin list page. Select events and search for the installed/updated autoupdater plugin. It now is configurable! The two new options are pre-filled with the origin Serendipity GitHub path. Change both to the new URLs (6) and (7). Version 1.4.0 has this already preset. This is important!
  4. Next, go to your BACKEND global “Configuration” → “General Settings” and enable the “autoupdate” option to search for “beta” releases. This as well gives you RC and full release versions.
  5. Now click the HOME top navigation button or the Blog name to open your BACKEND dashboard.
  6. It will now (or later *) show you that an upgrade is available. (*) If that has run before, it might show you an old update version for another ~6 hours. Upgrade to Serendipity Styx Edition. Follow the routine. Don't forget, if it gets stuck, just try to reload the upgrade page. Very easy!
  7. Open up the Spartacus plugin configuration and set this URL [5] to the custom mirror field. This enables to fetch the Styx additional plugin repository, highly recommended. When all is done, upgrade all other plugin updates via Spartacus, since some of them rely on Styx changes. Styx 2.1.0 and up have this already preset.
  8. Now, open up the global configuration again and see a new config option field inside “General Settings” to read the RELEASE file. Change it to the correct Styx path (8). Styx 2.1.0 and up have this already preset.
  9. From now on you are on the right track! The next short how-to section is about some important and recommended BACKEND changes.

Please attend:

  1. Fresh Styx installs will have to set the URLs too; In this mentioned order! (Except step a. for [4].).
  2. [ Update ]:
    With Styx 2.1++ releases, the Spartacus custom mirror g.[5] and the general setting h.[8] are already preset for new installations.
  3. [ Update ]:
    Newer versions of the Serendipity Autoupdater from this repository already also have [6] and [7] preset for new installations.
  4. [ Update ]:
    Since the Serendipity Styx 2.6-beta1 release (read the BLOG NOTES and scroll down to to the 2.6-beta1), you don't need to self-care about these URLs any more, neither for Spartacus, the Configuration, nor the Autoupdater!
  5. [ Update ]:
    Since the Serendipity Styx 2.9.5 release (read the BLOG NOTES) the recommended way of doing a migration upgrade is the normal upgrade method (read about it above in the upgrade guide) and not the Autoupdater!

The hitchhikers guide to migration Upgraders Styx Backend tuning:

  1. Open up your “Personal Settings”. See the force popup options is pre-filled with links. This means, the info button on the dashboard now opens some links embedded to the dashboard and another quick info hello box. If you like it, keep it. My preferred and recommended method here is: links,categories,tags. You'll notice the difference in the entry form.
    Another recommended option to use, is setting "simplified filters" to NO. This enables extended filter possibilities, like the un-mentioned subdirectory exclude item filter in the MediaLibrary, which is a huge performance helper when having multi-directories and lots of images.
  2. Option WYSIWYG Editor enabled? Why not! It definitely is a good one! And it is even better with the additional CKEditor Plus plugin installed.
  3. Option Default Dashboard Widgets? My recommendation is: Set it to NO. It spares some enormous place on the dashboard and the comment administrations is even better done via sidebar comment link. And it gives you some additional support, with from Styx 2.1+.
  4. If you want to get informed about plugin updates in the Dashboard (backends startpage) in future, install the event “plugup” plugin and check the depending option in the “spartacus” event plugin. (There is no actual recommendation to install this, since the normal plugin update is doing a better job.)
  5. In your Backend Themes, change to use the recommended Styx Backend. This also helps to remember that you have Styx on board!
  6. Upgraders, check if Configuration - Image Conversion Settings - Thumbnail max size option is set to 400. This is the default since Serendipity 2.0. In addition you might want to change exiting thumb images in Maintenance.
  7. Open up the configuration of the entryproperties event plugin. Change the movable item boxes to this new pair order:
    • Active Mark this entry as a Sticky Post
    • Active Empty movable grouping grid-(space-)box
    • Active Author
    • Active Password
    • Active Hide from article overview / frontpage
    • Active Hide content in RSS
    • Active Entries can be read by
    • Active Disable Markup plugins for this entry:
    • Active / Inactive Read permission: Author
    • Active / Inactive Read permission: Group
    • Active / Inactive Custom Fields

You will notice the last three may be activated or not by your needs only. Why this at all? Since this is one of the best pair-order options for the entry form, making it appear nice and smooth, without taking too much of the available place. You will notice, when opening up the entry form. If you don't have it installed, go and install it via Spartacus.

Styx new modemaintain and changelog event plugins are available, plugged as maintenance widgets. Upgraders have to install them via Spartacus themselves. And at last, you should read the Styx ChangeLog. This can (then) be done easily via the Backends Maintenance page. :) Definitely!

Fresh installs already supplied and activated the entryproperties, changelog and modemaintain plugins for you ... among others!

 

Normal in-Styx Edition Upgrades

Deflate a new Styx release zip items to your current installation, open up your Blog and then follow the presented update routine or use the autoupdate plugin, which does that easy and automatically for you.

Fresh Installation


Before the installation

Serendipity is a PHP-based web application. That means, to use Serendipity, you need to have access to a Web Server that has PHP support enabled. You upload the Serendipity files to that Web Server (by using FTP, SSH or other means) into a directory that is part of your Web Servers document tree.

After you have uploaded the files to your web space, you need to “open” the Serendipity application. You do that by opening an URL like http://example.com/serendipity/index.php.

SECURITY RECOMMENDATION: When you upload the Serendipity files to your webspace, this means temporarily everyone who knows the URL to your Blog would be able to use the Serendipity installer. To prevent unauthorized access, you should immediately secure your installation during this process. The best way to do this is by securing the Blog with a password by using a .htaccess file that you upload first, as outlined in the section Locking the Blog.

Serendipity Styx already comes with a secured installation, which uses a “two-factor authentication” (2FA) like token to exclusively bind the installation progress to the one being able to upload the files. You!

Token secured installation
Styx: Token secured installation

Requirements

Serendipity is tailored for the Apache Webserver. However, people are successfully running Serendipity with NGINX, Microsoft IIS and LightTPD. When using Serendipity on Windows servers, pay attention to always enter path references using forward slashes (‘/’) instead of the notation using backslashes (“C:\…\”).

For full operation, Serendipity relies on .htaccess files that your Virtual Host must allow. For Apache, this requires the Allow Override File Info Indexes Limit (or Allow Override All) option set to the directory of your Serendipity installation.

A current Serendipity Styx in branched 2/3 Series requires at least PHP 5.5/7.3 and fully enabled and working Cookie Session support. It requires the PCRE extension, and optionally makes use of the GD, iconv, xml, zlib and mbstring extensions. Serendipity is fully PHP 8.x compatible and encourages the use of PHP bytecode compilers like OPcache.

When operating Serendipity in PHP’s Safe Mode, you will not be able to use File Upload and SPARTACUS Plugin fetching facilities. Enabling error_reporting and display_errors (or directing this to a log file) is suggested to keep track of possible errors. The file_uploads directory should be turned ON if you want to have media file upload features. For graphic processing, you either require GDLib or ImageMagick.

It is very much suggested to DISABLE the register_globals, session.use_trans_sid and magic_quotes_* directives of PHP, which is already the default since at least PHP 5.

You require at least one of the following Database Extensions and a Database Server of the same kind: MySQL(i), PostgreSQL, SQLite.

Write access must be granted to:

  • .htaccess [created on installation]
  • serendipity_config_local.inc.php [created on installation]
  • archives/
  • templates_c/
  • uploads/
  • plugins/ (if you plan to use the Spartacus plugin)
  • templates/ (if you plan to use the Spartacus plugin)

Uploading Serendipity

You can install Serendipity into either your document root of the web server, or into any subdirectory you like. Make sure that you upload ALL files that you extracted from your Serendipity release .ZIP or .TGZ file, including empty directories. Make sure, your FTP editor doesn’t report any trouble or permission errors when uploading Serendipity files.

Permissions on files/directories

Very important to Serendipity are the directories archives, templates_c and uploads. The directory archives is used to store pre-generated files, the directory templates_c will contain automatically compiled HTML templates from the Smarty Templating Engine and the directory uploads will contain any media files you upload to your Blog. This means, all three folders will require write access for your webserver.

PHP usually runs as a specific user that is different from the FTP user account you use to upload files. So, if your FTP user is able to upload files, this does not necessarily mean, that the PHP process will be able to access the same files/directory. Depending on your webservers setup, you might need to change the permissions (CHMOD) of the three mentioned directory to something like 777 (read, write and execute permissions for everyone, meaning “world writable”), 775 (meaning read, write and execute permissions for the owner and the group of the files/directory, but not “everybody”). Which one to use is very specific to your webserver’s setup. Please ask your provider, if you are unsure which permissions you need to use!

On top of those three directories, Serendipity will also need to write the two files .htaccess and serendipity_config_local.inc.php into the root of the Serendipity installation. That means that also the directory where you upload the full Serendipity installation into needs to have permissions that allow the PHP server to create those two files - so remember to also set your top directory (like “serendipity” or “blog”) to 777 or 775. You can reset those permissions on the core directory after the installation to something like 744 again, because once the mentioned files are written, Serendipity only needs to alter those files.

If you plan to use the SPARTACUS plugin to download plugins and themes over the web, PHP also needs to be able to write to the directories plugins and templates.

Further permission-related questions are answered in our FAQ.

Installing

Once you have uploaded Serendipity to your web space you can call the installer interface via something like http://example.org/serendipity/index.php. It will take no longer than 1-2 minutes to install Serendipity.

On this screen, you will see a basic pre-installation report that shows you a diagnosis of your Web Server settings. All variables that possibly might create trouble are listed orange-coloured. You usually do not need to pay attention to those, unless you are experiencing errors. Here’s an example screenshot:

First page of the installer
First page of the installer

Fatal problems are shown in red color. The most usual case of a red error is if Serendipity cannot create the directories templates_c, archives or uploads. In this case, please follow the suggestions in the “Permissions on Files/Directories” step of this documentation.

On the bottom of the diagnosis screen, you can choose if you want to perform a “Simple installation” or the “Expert installation”. Both methods actually perform the same steps; however the “Simple installation” only shows you very few initial configuration options so that you can install Serendipity quickly. The “Expert installation” will ask you to enter every configuration directive.

Since the goal of this document is to show how fast you can install Serendipity, we will only discuss the “Simple installation” right now, so please click on that link and you will see a screen like this:

Simple installation options
Simple installation options

As you can see, this screen is divided into several sections.

Database Settings

In this section, you must enter the credentials to access the selected database. First you choose the database type you want to use for Serendipity. Serendipity will only show the database types that are available to PHP. Note, that your provider must have given you credentials to access your database, and that this database must already exist. Serendipity requires an empty database, so if you have not yet created a database, just do that via the SQL command “CREATE DATABASE serendipity” using your favourite SQL tool (phpMyAdmin, phpPgAdmin, sqliteAdmin).

Make sure, that you have read and correctly set “Preparing a database” for Serendipity before!

Now you just fill in the values you got from your provider for the host, user, password and database name fields.

General Settings

This section contains the most basic Blog setup options. First you enter the username and password for your Admin user. It is recommended to not use special characters like Umlauts for the username. Your username will not be displayed in the Blog to enhance login security - to display your username, the “real name” option will be used.

The E-Mail address of your admin user is very important, since you will receive trackback and comment notification emails to that address.

The Blog name and description will later be shown on the frontpage of your Blog. Of course, all those settings can later be changed!

As the last option of this section, you need to choose the language of your Blog. Note that this will be the default language for both your frontend of the Blog and the personal language of your editor. All other users are later able to define their own language for viewing your Blog! (See: “Personal Settings”.)

Complete installation

After you have entered all options, you click on the button “Complete installation”. Serendipity will then try to connect to your database. If that fails, it will inform you of this.

Also, Serendipity will perform checks and create directories, so it might ask you to create some more directories/permissions as discussed above.

If you ever have troubles because of wrong auto-detected directories or URLs, you might need to call the “Expert installation” wizard. This gives you several additional configuration options to indicate the used directories, database table prefixes etc. Note well that the Expert Installation will show you the path layout as it currently is configured; if you change the path/URL locations there, you need to enter values that reflect your ACTUAL layout, and not the layout you would want. If you want to install Serendipity into a different directory than displayed, you need to move the files via FTP/SSH there.

Else, Serendipity will create the required database tables and sets up your Blog as configured:

Results of the database tables creation
Results of the database tables creation

This screen tells you that Serendipity has created the tables, inserted your admin user account, installed default plugins and auto-created the “.htaccess” file.

REMEMBER WELL that if you ever want to reinstall Serendipity from scratch, you need to DROP all Serendipity-created Database tables. Else, reinstalling into the same database will Serendipity lead to think that it shall not re-create the tables and authors. This would then lead to duplicate inserted plugins and non-matching user credentials you entered!

Accessing your Blog Frontend

After the installation, the screen above showed you a link to “Visit your new Blog here”. You can click on this, and then you should see your empty Blog like this:

Index page of an empty Blog
Index page of an empty Blog

If you instead see a “HTTP 500” error screen, this means that your Web Server did not allow Serendipity to create custom “.htaccess” directives. In this case, you can just delete the file “.htaccess”. Serendipity can operate well without this file, BUT you will not be able to use “pretty URLs”. Those pretty URLs are configured via the “URL Rewriting” option inside Serendipity Configuration.

Accessing the Admin panel

After you’ve installed Serendipity, you most probably want to access the admin interface to customize further options. You can do that by calling your URL http://example.org/serendipity/serendipity_admin.php) - a link to the admin interface is also shown on the Blog Frontend, as you might have noticed.

Accessing this interface will give you a login screen:

Login screen
Login screen

Enter the user details there, which you specified in the installation. By default this is username “John Doe” and password “john”. If you check the box “Save information” below, this will make Serendipity save a persistent Cookie on your client, and you can auto-login to your panel any time you want. Note that if you are not the only person using your browser, you may not want to do this. :-)

Then you will see the admin interface:

Dashboard
Dashboard

The left navigation takes you to specific sections of your Blog:

Frontpage

The Backends “Frontpage” - also named the “Dashboard” - normally just shows you the basic page. Here, specific plugins might show you a specific output, which currently are: The last (5) “Comments” and (draft entries) “In Progress”.

Personal Settings

The button with the three gears on the upper right of the page will lead you to your personal settings section. The personal settings section will show all user-specific options to your currently logged-in user. There you can change your username, your password and also the language you want to see for the Admin interface.

The most important distinct option is whether to use the “WYSIWYG” editor. This will show you a Word-like interface for creating Blog entries. It makes life easy, and if you do not know any HTML at all, you will be very glad about this editor that will allow you to insert images, links and text formatting at ease. This option can also be changed later, if you happen to dislike the WYSIWYG editor, or if you’re missing it.

Further on, you can set the behaviour of the Dashboard widgets. Default is “ON”, but Styx recommends using it NOT, to allow to reduce this to an informational only widget, much smaller and leaving enough space for additional ‘snapped’ widgets.

Simplified filters reduce some of the extended possibilities of Serendipity. This is a good start for the Beginners, but will not let you recognize some more advanced tools. Take a ride when you are ready!

Personal settings
Personal settings

Content

This section contains all relevant options to create and maintain entries and maintain categories.

Entry editor
Entry editor

Media

The media section allows you to upload and maintain images and documents you uploaded and can embed into entries.

Upload form for the media database
Upload form for the media database

Activity

This section contains options to maintain comments to your entries and manage spam protection settings.

Settings

This section covers the configuration of your Blog, the users and groups that are allowed to login to your Blog, and importing/exporting entries.

Note that the “Configuration” item will show you all the options you would see in the Expert Installation. There you can configure all the detailed options of your Blog, like URL Rewriting, Permalinks, Charsets etc.

Configuration section
Configuration section

The sections Themes and Plugins allow you to configure and setup plugins as well as choose the layout of your Blog

Theme selection
Theme selection
Plugin configuration
Plugin configuration

Maintenance

This section is for “maintaining” specific system tasks, as there are: the “Integrity” verifier, the “MediaLibrary Synchronizer”, a Smarty “compile” cleanup task, the “Change/Debug”-log file viewer, the “503 Maintenance Service Mode”, tools to “import/export” Blogs, the “Spamblock”-log cleaner and the “UTF8MB4” migration task.

Maintenance section
Maintenance section

And what next?

Now that you have successfully installed Serendipity Styx, go ahead and explore. Create some entries, categories, or install a few plugins via Spartacus, that you can also find here in the Styx Spartacus WWW mirror. A recommended one for immediate install for example would be the “Serendipity Autoupdate” event plugin! The Spartacus interface is in most cases self-explanatory and open for experiments.

If you have any questions, feel free to come to the discussion forums or to browse the docs section for further documentation.

Ian Styx (ophian)Maintainer

John Ian Styx has more than 20 years of experience in the IT market as a developer and from 2003 as a Serendipity lover.