Tweet Nest

A browsable, searchable and easily customizable archive and backup for your tweets

by Andy Graulund

(screenshot)

Ever thought to yourself that you wish there was some way you could take a look back and see what you tweeted around this time last year?

Or perhaps you remember that time you tweeted about that hilarious viral video, and now you can’t find it?

By installing Tweet Nest on your own web server, now you can! Features include:

Archive
Use Tweet Nest to easily store, browse and search amongst your tweets to find exactly what you're looking for, and let others do the same. New-style retweets, geographic places and links to original tweets included.
Backup
Additionally, Tweet Nest serves as a backup of your precious tweets on your own server. Tweets that might grow too old to be retrieved from Twitter.com will not fade out here, allowing you to go back in time as much as possible.
Media
Tweet Nest offers an easier way of viewing your tweets at a glance, as they include thumbnails of media like photos hosted on common providers, such as TwitPic. Additionally, for every month view you get an elegant yet simple bar chart of the amount of tweets, retweets and replies you've sent every day.
Customize!
Tweet Nest is something you host on your own server, so if you know your web development awesomesauce, you can make your tweet archive your own by easily changing color values in the config file, or even changing the behaviour of the whole thing by changing the stylesheet or some of the other code if you so wish.

Looking for a demo? Check out my own tweet archive, which I’ve customized with my own background image and color scheme.

Installation

Tweet Nest is programmed in PHP and requires a MySQL database to work. It’s been tested in LAMP environments, i.e. Linux/Apache/MySQL/PHP. It may work on other types of servers, but you’ll have to figure that out for yourself. The minimum requirements of Tweet Nest are:

You can check out what versions you have by asking your web host.

When you’re confident that your server fulfills the above requirements, click the button below to download a zip archive, and then read on.

Download Tweet Nest Version 1.1 BETA

Step 1

Then it’s time to upload it to your server. All files need to be uploaded in the folder hierarchy found in the zip file. Specifically, included are two so-called .htaccess files, one directly in the folder and one in the maintenance folder. If you don’t see those on your server after uploading, you need to rename the RENAME-ME.htaccess files in these two places to .htaccess each.

If you do already see the .htaccess files, you can delete the RENAME-ME files. They’re not needed.

Step 1

Before setting up Tweet Nest, due to Twitter’s new policies, it is now required that you register your Tweet Nest installation with Twitter. To do this, go to Twitter’s Developer Site, log in with your Twitter credentials, and click the “Create an application” button on the “My applications” page. The details you provide here are not crucial, however you should probably include that it’s for a tweet archive. It is important you fill in the URL of your Tweet Nest installation in both the “Website” and “Callback URL” fields, otherwise your Tweet Nest installation will not be able to get access to Twitter.

Once you’ve registered with Twitter, make sure you’ve received two strings labeled consumer key and consumer secret. You will need them in the next step.

Step 2

You can now run the built-in setup guide where you can enter your configuration information.

The first part of the setup guide page is devoted to the registration with Twitter as mentioned above. Before filling in anything else, first copy/paste in the consumer key and consumer secret strings from above, and then click the “Sign in with Twitter” button. You will be redirected to Twitter in order to log in with your Twitter credentials, and then you will be sent back to the setup guide page, where there should now be a green label reading “Authorized”. And then you’re free to continue the setup.

The rest of the setup guide page works mostly like any other installable web app, and it should hopefully be easy for you to fill it out. However, you may run into one or two errors. Not every error can be fixed, but those that can will be explained here:

  • If it tells you that your config file is not writable, you have to make sure the server can write to the inc/config.php file. This is usually done by temporarily giving every user on the server write privileges to that file. On Linux servers, this is displayed as rw-rw-rw- or 0666. You can usually do this through your FTP app by right clicking and choosing “Properties” or “Get Info”. And once you’re done with the set up, you need to set your config file back to normal privileges. On a Linux server, this is usually rw-r--r-- or 0644.
  • If you get a MySQL access denied error, you’ve probably misspelt your database info.
  • If you get a blank page or a lot of syntax errors, you are probably running a PHP version less than 5.1, which this web app requires.
Step 3

Great! Now that you’re done with the setting up, there’s a couple of things that need done. You are told this by the set-up guide, but what is most important is the following: You have to load in your user data and tweets. This is done by pointing your browser at two maintenance pages that spend some time loading in the aforementioned. If you set an admin password in the set-up guide, you’ll have to use it here, along with your Twitter screen name. The two files are:

  • maintenance/loaduser.php — This one loads in your user information from Twitter: For example, this is real name, your icon, your location and more. This’ll need to be loaded in at least once, when you’re setting up Tweet Nest, but will also need to be loaded once you change icon or anything else like that.
  • maintenance/loadtweets.php — This is the important one: By running this file, you load in your tweets to the archive. If there’s no tweets in the archive, it loads all of them, but if there are, it loads everything new since the last one archived. In other words, this needs to be run often if you want to keep your archive up to date.

An optional step to keep your archive up to date is to run loadtweets.php automatically in a cron job every day. When you run it through your browser, it displays at the bottom of the page a command you might use to run that script in the terminal of your server. Double-check that it works by trying it out, and then add it as a daily or hourly cron job (see the Wikipedia article for help).

That’s it! It should now be fully functional on your site. If you want to customize it further, read on. If it still doesn’t work, head over to our support forum. And if you’ve got questions, be sure to check out the Tweet Nest FAQ first.

Upgrading

If you are upgrading from an older version to the newest version, please download the newest version of Tweet Nest and upload all files except for inc/config.php to your Tweet Nest installation, overwriting old files.

After that, you have to register your Tweet Nest installation with Twitter, as described in the guide above, in order to continue loading your tweets from Twitter.

When that is done, point your browser to the authorize.php file found in your Tweet Nest installation’s root folder. It will allow you to enter your consumer key and consumer secret strings, and finish the registration. After that, everything should work once again.

◈ ◈ ◈

If you want to add support for new image services that have been added in some (but not all) newer versions to older tweets, you have to clear your database and reload all tweets again after having done the above.

If you run into troubles upgrading, head over to our support forum. See all changes between Tweet Nest versions on the changelog page.

Importing your Twitter archive

Starting in version 1.1, it is now possible to import your Twitter archive (found on your account settings page on Twitter) into Tweet Nest, which makes it possible to import tweets that are otherwise too old to load directly from Twitter.

This functionality was created by tralafiti, and he’s written the following guide on how to import your Twitter archive into Tweet Nest:

  • First, place your downloaded JSON archive files (data/js/tweets/year_month.js) directly in the archive folder (archive/year_month.js)
  • On new Tweet Nest installations:
    1. Follow the Tweet Nest instructions first
    2. Right after the maintenance/loaduser.php step, run maintenance/loadarchive.php
  • On existing installations:
    1. Be sure not to overwrite your inc/config.php or you will have to setup your instance again
    2. Run upgrade.php
    3. Run maintenance/loadarchive.php

The importer keeps track of its progress in maintenance/loadarchivelog.txt if it's writable. Should the script die for some reason (PHP time limit e.g.), just run it again.

If you have a large archive (10K+ tweets), I would recommend to do the one-time import through the command line (php -f maintenance/loadarchive.php)

If you run into any problems with the import process, please leave your thoughts on this thread on GitHub.

Customization

(Style configuration)

Tweet Nest is all about customization! I don’t want this to be the sort of factory thing that everyone has installed and every instance of it looks the same as everywhere else, I want people to customize it and make it their own! And so, for starters, it’s very easy to make some defining colour changes that make your tweet archive unique.

If you open up inc/config.php in any raw text editor like Notepad, you will find a Style section below your configuration information. This is where almost all of the colours used in the Tweet Nest interface are defined. If you want to change any of them, simply give it a go and save & reupload the file and you’ll see the changes instantly. All colour values can be given values that can be found in any CSS file, such as #fff, rgb(255, 255, 255) or white.

However, a couple of colours are equivalent to those found on your Twitter profile and thus you can simply set that colour value to profile, and it’ll be the same as the equivalent on your Twitter profile! (If this is outdated, run maintenance/loaduser.php.) Not every value works like this, but those that do are clearly marked in the config file.

Of course, if you want more power, you can also change the CSS file directly or even create your own and link to it in the config. These can even be repackaged for other people to use.

Even more advanced, there is also rudimentary support for extensions which empower Tweet Nest to do more cool stuff. They can bind to different types of hooks in the Tweet Nest app and thus perform actions when those hooks are reached. Right now, there’s only enhanceTweet (do stuff to tweet while it is being loaded) and displayTweet (do stuff to tweet before it’s being displayed), but more might come in a subsequent version if you ask me. There’s no further documentation on this, but look at the one extension made, found in extensions/images.php to see how one is built.

If you end up customizing your installation of Tweet Nest, send a link to me! I want to see!

Oh, and by the way: Tweet Nest is on GitHub — and it’s open source, naturally.

Who made this?

My name is Andy Graulund, and I’m a guy who lives in Copenhagen, Denmark. My Twitter screen name is , and you can follow me on Twitter for updates to this script and other cool stuff.

I have a website called Pongsocket that lists my other projects.

Additionally, newer versions of Tweet Nest have been made possible by contributions on GitHub, with special thanks to Victor Jacobs.

Awesome illustration by Matt Miles