Installation Guide

Installing Tiny Tiny RSS for the first time

Before you begin, you'll need to verify the following:

1. You need access to a hosting/VDS running a http server and a database (mysql or postgresql).
2. You will need to acquire database credentials, i.e. login, password, and a database name. If you don't have a database already created, you need to do so before installing. Tiny Tiny RSS can coexist with other applications in a shared database, creating a dedicated one is not necessary.
3. Your http server should be running PHP version 5.3 or later. Having an accelerator like php-apc is highly recommended.

After you have gone through the above list, you can proceed to the installation.

1. Unpack the distribution .tar.gz archive into destination directory.

tar zxfv Tiny-Tiny-RSS-1.x.x.tar.gz

It's recommended to rename the directory to tt-rss for brevity.

mv Tiny-Tiny-RSS-1.x.x tt-rss

Alternatively, you can unpack the distribution on your local machine and upload files to the server using FTP or any other means available to you.

2. Verify that you can open http://your.site.com/tt-rss/install/

3. Proceed with the installation using the easy installer. It will ask your database credentials and a full URL on which tt-rss will be accessed, for example http://your.site.com/tt-rss/install/. It is required that the URL is an externally accessible one (if any), don't use localhost there, it will break PUSH support. If you are deploying tt-rss on LAN, you can disregard this requirement.

4. The easy installer will generate config.php for you, after you have entered your database credentials and initialized tt-rss database. You will need to either copy text from the installer and paste it into config.php on the server, or, if possible, the installer will be able to do it for you automatically.

5. It is suggested that you read through config.php to see if you need to enable additional functionality or change default configuration values.

5. After finishing with the installer, open your Tiny Tiny RSS installation at http://your.site.com/tt-rss/ and login with default credentials (username: admin, password: password).

6. Go to preferences and change your password!

7. You will also need to decide on the method tt-rss uses to update feeds. This is a separate topic, outlined in UpdatingFeeds.

7. If all went well, you may proceed to use tt-rss normally. Create a separate non-admin user, login under it, and start importing your feeds, subscribing, and configure it to your taste.

8. That's all!

Don't forget to read UpdatingFeeds otherwise your feeds won't update automatically.

Take a look at available plugins

There are many plugins written for tt-rss. You can see the list here: Plugins.

Upgrading Tiny Tiny RSS

It is highly recommended to temporarily disable any third party themes and user CSS customizations before upgrading. Don't forget to empty your browser cache if you experience weird bugs right after upgrading.

Note that you should upgrade to the latest version available, installing intermediate releases sequentially is not needed.

1A. In-place upgrading

The recommended way is in-place upgrading using the updater plugin. There are several specific requirements for updater to work: the user you run updater as should have writable access both to tt-rss and tt-rss parent directories on your web server.

For example, if tt-rss is installed at /var/www/tt-rss, both /var/www and /var/www/tt-rss need to be writable by the updater user.

In case of web updater, the user is whatever your site runs PHP under (for example, www-data). In case of CLI updating, you can easily run the plugin as an arbitrary user.

Please note that updater renames your old tt-rss directory and replaces it with a pristine new one. You will need to copy all locally modified files (e.g. plugins, CSS themes, modified templates, .htaccess files) back from the previous installation (it will be renamed as tt-rssXXXXX in a parent directory). The only exception to this are feed icons and config.php which are copied into the new directory automatically.

Warning: Third party plugins you have been using might not be compatible with the newer tt-rss version. If you experience crashes right after upgrading, start with disabling all third party plugins to see if that resolves it.

Warning: In 1.7.6 in-place updater requires CURL. It will fail with RC=2 when CURL functions are not present in PHP.

Warning: Do not copy cache/ directories from your old tt-rss directory after upgrading.

You will need to enable the updater plugin by adding it to PLUGINS directive in config.php if it's not enabled yet.

Afterwards, go to Preferences -> Update Tiny Tiny RSS and follow instructions.

You can also update from the command line if you have PHP CLI access by running update.php --update_self.

Proceed to section 2.

1B. Manual upgrading

If, for some reason, you are unable to use the in-place updater or updating from an older version which doesn't have it yet, proceed with manual upgrade.

Download the new archive from tt-rss.org. Unpack it. Replace your old tt-rss directory with a newer one, optionally copying config.php, contents of feed-icons, and your other modified files - plugins, CSS files, etc.

Warning: Third party plugins you have been using might not be compatible with the newer tt-rss version. If you experience crashes right after upgrading, start with disabling all third party plugins to see if that resolves it.

Proceed to the next section.

2. Merging new config.php directives and updating the database

After the files have been upgraded by newer versions, open tt-rss. It may complain about missing directives in config.php. If that happens, you will need to either merge new stuff from config.php-dist to your config.php or remove config.php and rerun the installer (take note to copy previous value of FEED_CRYPT_KEY if you have feeds with authentication enabled).

Warning: DO NOT INITIALIZE DATABASE when upgrading. This will remove ALL your tt-rss data.

Afterwards, you may be redirected to the database updater. Log in with admin credentials and follow instructions.

Finishing that, you should be able to use tt-rss normally by logging in with your normal account.

3. Post-upgrade tasks

1. You might need to clear your browser cache if you experience CSS or script-related issues, older scripts might have stuck in it.
2. Do not copy cache directories from your old tt-rss version, it is unnecessary and potentially creates problems if you don't preserve file modification times.
2. If you are using an accelerator like php-apc you might need to restart apache if older cached versions of PHP files got stuck in cache (this happens rarely, but is a possibility).