UPGRADE

   1 Upgrading
   2 =========
   3
   4 IMPORTANT NOTE: StatusNet 0.7.4 introduced a fix for some
   5 incorrectly-stored international characters ("UTF-8"). For new
   6 installations, it will now store non-ASCII characters correctly.
   7 However, older installations will have the incorrect storage, and will
   8 consequently show up "wrong" in browsers. See below for how to deal
   9 with this situation.
  10
  11 If you've been using StatusNet 0.7, 0.6, 0.5 or lower, or if you've
  12 been tracking the "git" version of the software, you will probably
  13 want to upgrade and keep your existing data. There is no automated
  14 upgrade procedure in StatusNet 0.9.9. Try these step-by-step
  15 instructions; read to the end first before trying them.
  16
  17 0. Download StatusNet and set up all the prerequisites as if you were
  18    doing a new install.
  19 1. Make backups of both your database and your Web directory. UNDER NO
  20    CIRCUMSTANCES should you try to do an upgrade without a known-good
  21    backup. You have been warned.
  22 2. Shut down Web access to your site, either by turning off your Web
  23    server or by redirecting all pages to a "sorry, under maintenance"
  24    page.
  25 3. Shut down XMPP access to your site, typically by shutting down the
  26    xmppdaemon.php process and all other daemons that you're running.
  27    If you've got "monit" or "cron" automatically restarting your
  28    daemons, make sure to turn that off, too.
  29 4. Shut down SMS and email access to your site. The easy way to do
  30    this is to comment out the line piping incoming email to your
  31    maildaemon.php file, and running something like "newaliases".
  32 5. Once all writing processes to your site are turned off, make a
  33    final backup of the Web directory and database.
  34 6. Move your StatusNet directory to a backup spot, like "statusnet.bak".
  35 7. Unpack your StatusNet 0.9.9 tarball and move it to "statusnet" or
  36    wherever your code used to be.
  37 8. Copy the config.php file and the contents of the avatar/, background/,
  38    file/, and local/ subdirectories from your old directory to your new
  39    directory.
  40 9. Copy htaccess.sample to .htaccess in the new directory. Change the
  41    RewriteBase to use the correct path.
  42 10. Rebuild the database.
  43
  44     NOTE: this step is destructive and cannot be
  45     reversed. YOU CAN EASILY DESTROY YOUR SITE WITH THIS STEP. Don't
  46     do it without a known-good backup!
  47
  48     If your database is at version 0.8.0 or higher in the 0.8.x line, you can run a
  49     special upgrade script:
  50
  51         mysql -u<rootuser> -p<rootpassword> <database> db/08to09.sql
  52
  53     If you are upgrading from any 0.9.x version like 0.9.6, run this script:
  54
  55         mysql -u<rootuser> -p<rootpassword> <database> db/096to097.sql
  56
  57     Despite the name, it should work for any 0.9.x branch.
  58
  59     Otherwise, go to your StatusNet directory and AFTER YOU MAKE A
  60     BACKUP run the rebuilddb.sh script like this:
  61
  62         ./scripts/rebuilddb.sh rootuser rootpassword database db/statusnet.sql
  63
  64     Here, rootuser and rootpassword are the username and password for a
  65     user who can drop and create databases as well as tables; typically
  66     that's _not_ the user StatusNet runs as. Note that rebuilddb.sh drops
  67     your database and rebuilds it; if there is an error you have no
  68     database. Make sure you have a backup.
  69     For PostgreSQL databases there is an equivalent, rebuilddb_psql.sh,
  70     which operates slightly differently. Read the documentation in that
  71     script before running it.
  72 11. Use mysql or psql client to log into your database and make sure that
  73     the notice, user, profile, subscription etc. tables are non-empty.
  74 12. Turn back on the Web server, and check that things still work.
  75 13. Turn back on XMPP bots and email maildaemon. Note that the XMPP
  76     bots have changed since version 0.5; see above for details.
  77
  78 If you're upgrading from very old versions, you may want to look at
  79 the fixup_* scripts in the scripts directories. These will store some
  80 precooked data in the DB. All upgraders should check out the inboxes
  81 options below.
  82
  83 NOTE: the database definition file, laconica.ini, has been renamed to
  84 statusnet.ini (since this is the recommended database name). If you
  85 have a line in your config.php pointing to the old name, you'll need
  86 to update it.
  87
  88 NOTE: the 1.0.0 version of StatusNet changed the URLs for all admin
  89 panels from /admin/* to /panel/*. This now allows the (popular)
  90 username 'admin', but blocks the considerably less popular username
  91 'panel'. If you have an existing user named 'panel', you should rename
  92 them before upgrading.
  93
  94 Notice inboxes
  95 --------------
  96
  97 Notice inboxes are now required. If you don't have inboxes enabled,
  98 StatusNet will no longer run.
  99
 100 UTF-8 Database
 101 --------------
 102
 103 StatusNet 0.7.4 introduced a fix for some incorrectly-stored
 104 international characters ("UTF-8"). This fix is not
 105 backwards-compatible; installations from before 0.7.4 will show
 106 non-ASCII characters of old notices incorrectly. This section explains
 107 what to do.
 108
 109 0. You can disable the new behaviour by setting the 'db''utf8' config
 110    option to "false". You should only do this until you're ready to
 111    convert your DB to the new format.
 112 1. When you're ready to convert, you can run the fixup_utf8.php script
 113    in the scripts/ subdirectory. If you've had the "new behaviour"
 114    enabled (probably a good idea), you can give the ID of the first
 115    "new" notice as a parameter, and only notices before that one will
 116    be converted. Notices are converted in reverse chronological order,
 117    so the most recent (and visible) ones will be converted first. The
 118    script should work whether or not you have the 'db''utf8' config
 119    option enabled.
 120 2. When you're ready, set $config['db']['utf8'] to true, so that
 121    new notices will be stored correctly.