Updating: Difference between revisions

From diaspora* project wiki
(Rack::SSL)
(I moved the update from 0.4 to 0.5 to below the basic update instructions, and added a change in the update procedure to recommend 2.1 for 0.5 or later versions. I also shortened the 'rvm use' command to be 2.1 or 2.0 as they grab the latest release.)
Line 5: Line 5:
These guides are generally for production setups, if you're developing for diaspora* you should know which steps are relevant to update your development setup. If you run into any troubles, seek help via the usual channels.
These guides are generally for production setups, if you're developing for diaspora* you should know which steps are relevant to update your development setup. If you run into any troubles, seek help via the usual channels.


== Updating diaspora* 0.4 to diaspora* 0.5 ==


Since there are a couple of major changes in upgrading to 0.5 which involve
manual action, we provide a step by step guide. Please ensure to update
to diaspora* 0.4 prior these steps.
{{Note|This update will take from half an hour up to several hours, as it
contains a long running migration, especially on MySQL/MariaDB.}}
{{Note|If, and only if, you were testing the release candidate, skip this guide, run <tt>git checkout master && git pull</tt> and proceed with the normal update instructions below.}}
<ol>
<li>Make a backup of at least the database.</li>
<li>Take down diaspora*.</li>
<li>If you're on PostgreSQL run <tt>export DB=postgres RAILS_ENV=production</tt>, if you're on MySQL/MariaDB run <tt>export DB=mysql RAILS_ENV=production</tt>.
If you encounter a <code>rake aborted! NameError: uninitialized constant Rack::SSL</code> in the rest of this guide, that means you didn't execute this step correctly.</li>
<li>Run <tt>bundle exec sidekiq</tt>, wait 5 minutes and take it down again with <tt>Ctrl+C</tt>.</li>
<li>If you modified <tt>public/default.html</tt>, <tt>public/404.html</tt>, <tt>public/422.html</tt> or <tt>public/500.html</tt> take a backup of the changes, they will be gone or overwritten. Run <tt>git checkout Gemfile.lock db/schema.rb public/*.html</tt>. Run <tt>git stash</tt> to preserve any other uncommitted changes. You can later restore stashed changes with <tt>git stash pop</tt>.</li>
<li>Update RVM with <tt>rvm get stable</tt>. Install Ruby 2.1 with <tt>rvm install 2.1</tt>.</li>
<li>Update diaspora with <tt>git pull</tt>.</li>
<li>Activate the new Ruby with <tt>cd .. && cd -</tt>.</li>
<li>Install the latest Bundler with <tt>gem install bundler</tt>.</li>
<li>Install the dependencies with <tt>bin/bundle install --without development test</tt>. CAREFUL: Do not run any commands that are suggested at the end of this step, that was already done for you.</li>
<li>Verify you didn't run any additional commands already done for you : run <tt>git status</tt> and delete any untracked files residing in <tt>db/migrate</tt>.</li>
<li>Edit <tt>config/initializers/secret_token.rb</tt>, replace <tt>secret_token</tt> with <tt>secret_key_base</tt>:
<syntaxhighlight lang="ruby">
# Old
Rails.application.config.secret_token = '***********...'
# New
Diaspora::Application.config.secret_key_base = '*************...'
</syntaxhighlight>
</li>
<li>If you're using MySQL/MariaDB, edit <tt>config/database.yml</tt>: Replace <tt><span style="color: red;">charset: utf8</span></tt> with <tt><span style="color: red;">encoding: utf8mb4</span></tt>, notice how the key changed! Replace <tt><span style="color: red;">collation: utf8_bin</span></tt> with <tt><span style="color: red;">collation: utf8mb4_bin</span></tt>. Have a look at the updated <tt>config/database.yml.example</tt> if you need additional guidance in this step.</li>
<li>Run <tt>bin/rake db:migrate</tt>, this will take quite a while but you should occasionally check if it failed and seek assistance if it happened to fail.</li>
<li>Run <tt>bin/rake tmp:cache:clear assets:precompile</tt>. This steps now generates <tt>public/404.html</tt>, <tt>public/422.html</tt> and <tt>public/500.html</tt>.</li>
<li>You can now start diaspora* again as you're used to.</li>
</ol>
You should now compare your <tt>config/diaspora.yml</tt> to the updated <tt>config/diaspora.yml.example</tt>, for example with <tt>vimdiff</tt>. Notable changes, not only limited to the configuration, are:
* The surrounding markup for the custom splash page changed slightly, please refer to the [https://github.com/diaspora/diaspora/blob/master/Changelog.md#custom-splash-page-changes changelog].
* If you're using Paypal donations, the settings in <tt>diaspora.yml</tt> for it changed, in order to support the unhosted button. Please take a look at the updated <tt>diaspora.yml.example</tt>.
* The default for including jQuery from a CDN has changed. If you want to continue to include it from a CDN, please explicitly set the <tt>jquery_cdn</tt> setting to true in <tt>diaspora.yml</tt>.
* There's a new feature to automatically prune inactive accounts, if you want to enable it please refer to the [https://github.com/diaspora/diaspora/blob/master/Changelog.md#new-maintenance-feature-to-automatically-expire-inactive-accounts changelog].
* There's a new feature to proxy embedded images from external sources through your server, strengthening your users privacy. If you want to enable it please refer to [[Camo]].
* diaspora* 0.5 includes a preview of the new chat feature, if you want to play with it, have a look at [[Vines]]. We do not generally recommend enabling this yet.


= General directions =  
= General directions =  
Line 64: Line 19:
</syntaxhighlight>
</syntaxhighlight>


If you are upgrading to diaspora version 0.3 or later, you should install Ruby 2.0.0:
If you are upgrading to diaspora version 0.5 or later, you should install Ruby 2.1


<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
rvm install ruby 2.0.0  
rvm install ruby 2.1
rvm use 2.0.0
rvm use 2.1
</syntaxhighlight>
 
 
If you are upgrading to diaspora version 0.4.x or earlier, you should install Ruby 2.0
 
<syntaxhighlight lang="bash">
rvm install ruby 2.0
rvm use 2.0
</syntaxhighlight>
</syntaxhighlight>


Line 113: Line 76:


Now you need to restart Diaspora. To do this with the standard startup method you need to get to the place where you run <tt>./script/server</tt>, hit <tt>Ctrl+C</tt>, open a new shell, and run it again.
Now you need to restart Diaspora. To do this with the standard startup method you need to get to the place where you run <tt>./script/server</tt>, hit <tt>Ctrl+C</tt>, open a new shell, and run it again.
== Updating diaspora* 0.4 to diaspora* 0.5 ==
Since there are a couple of major changes in upgrading to 0.5 which involve
manual action, we provide a step by step guide. Please ensure to update
to diaspora* 0.4 prior these steps.
{{Note|This update will take from half an hour up to several hours, as it
contains a long running migration, especially on MySQL/MariaDB.}}
{{Note|If, and only if, you were testing the release candidate, skip this guide, run <tt>git checkout master && git pull</tt> and proceed with the normal update instructions below.}}
<ol>
<li>Make a backup of at least the database.</li>
<li>Take down diaspora*.</li>
<li>If you're on PostgreSQL run <tt>export DB=postgres RAILS_ENV=production</tt>, if you're on MySQL/MariaDB run <tt>export DB=mysql RAILS_ENV=production</tt>.
If you encounter a <code>rake aborted! NameError: uninitialized constant Rack::SSL</code> in the rest of this guide, that means you didn't execute this step correctly.</li>
<li>Run <tt>bundle exec sidekiq</tt>, wait 5 minutes and take it down again with <tt>Ctrl+C</tt>.</li>
<li>If you modified <tt>public/default.html</tt>, <tt>public/404.html</tt>, <tt>public/422.html</tt> or <tt>public/500.html</tt> take a backup of the changes, they will be gone or overwritten. Run <tt>git checkout Gemfile.lock db/schema.rb public/*.html</tt>. Run <tt>git stash</tt> to preserve any other uncommitted changes. You can later restore stashed changes with <tt>git stash pop</tt>.</li>
<li>Update RVM with <tt>rvm get stable</tt>. Install Ruby 2.1 with <tt>rvm install 2.1</tt>.</li>
<li>Update diaspora with <tt>git pull</tt>.</li>
<li>Activate the new Ruby with <tt>cd .. && cd -</tt>.</li>
<li>Install the latest Bundler with <tt>gem install bundler</tt>.</li>
<li>Install the dependencies with <tt>bin/bundle install --without development test</tt>. CAREFUL: Do not run any commands that are suggested at the end of this step, that was already done for you.</li>
<li>Verify you didn't run any additional commands already done for you : run <tt>git status</tt> and delete any untracked files residing in <tt>db/migrate</tt>.</li>
<li>Edit <tt>config/initializers/secret_token.rb</tt>, replace <tt>secret_token</tt> with <tt>secret_key_base</tt>:
<syntaxhighlight lang="ruby">
# Old
Rails.application.config.secret_token = '***********...'
# New
Diaspora::Application.config.secret_key_base = '*************...'
</syntaxhighlight>
</li>
<li>If you're using MySQL/MariaDB, edit <tt>config/database.yml</tt>: Replace <tt><span style="color: red;">charset: utf8</span></tt> with <tt><span style="color: red;">encoding: utf8mb4</span></tt>, notice how the key changed! Replace <tt><span style="color: red;">collation: utf8_bin</span></tt> with <tt><span style="color: red;">collation: utf8mb4_bin</span></tt>. Have a look at the updated <tt>config/database.yml.example</tt> if you need additional guidance in this step.</li>
<li>Run <tt>bin/rake db:migrate</tt>, this will take quite a while but you should occasionally check if it failed and seek assistance if it happened to fail.</li>
<li>Run <tt>bin/rake tmp:cache:clear assets:precompile</tt>. This steps now generates <tt>public/404.html</tt>, <tt>public/422.html</tt> and <tt>public/500.html</tt>.</li>
<li>You can now start diaspora* again as you're used to.</li>
</ol>
You should now compare your <tt>config/diaspora.yml</tt> to the updated <tt>config/diaspora.yml.example</tt>, for example with <tt>vimdiff</tt>. Notable changes, not only limited to the configuration, are:
* The surrounding markup for the custom splash page changed slightly, please refer to the [https://github.com/diaspora/diaspora/blob/master/Changelog.md#custom-splash-page-changes changelog].
* If you're using Paypal donations, the settings in <tt>diaspora.yml</tt> for it changed, in order to support the unhosted button. Please take a look at the updated <tt>diaspora.yml.example</tt>.
* The default for including jQuery from a CDN has changed. If you want to continue to include it from a CDN, please explicitly set the <tt>jquery_cdn</tt> setting to true in <tt>diaspora.yml</tt>.
* There's a new feature to automatically prune inactive accounts, if you want to enable it please refer to the [https://github.com/diaspora/diaspora/blob/master/Changelog.md#new-maintenance-feature-to-automatically-expire-inactive-accounts changelog].
* There's a new feature to proxy embedded images from external sources through your server, strengthening your users privacy. If you want to enable it please refer to [[Camo]].
* diaspora* 0.5 includes a preview of the new chat feature, if you want to play with it, have a look at [[Vines]]. We do not generally recommend enabling this yet.


== Updating a development install  ==
== Updating a development install  ==

Revision as of 16:15, 14 October 2015

This page contains specific directions on how to update diaspora*, if any special steps are necessary. If there are no special steps necessary refer to the general guide towards the end of the page.

Update guides

These guides are generally for production setups, if you're developing for diaspora* you should know which steps are relevant to update your development setup. If you run into any troubles, seek help via the usual channels.


General directions

NoteNote:Updating Diaspora is fairly straight forward. But sometimes there are special procedures or updates, so always read the changelog first.

RVM

In case you followed the recommended setup and are on RVM, update RVM first:

rvm get stable

If you are upgrading to diaspora version 0.5 or later, you should install Ruby 2.1

rvm install ruby 2.1 
rvm use 2.1


If you are upgrading to diaspora version 0.4.x or earlier, you should install Ruby 2.0

rvm install ruby 2.0
rvm use 2.0

Updating a production install

We need to update the code first:

git checkout Gemfile.lock db/schema.rb # Discard uninteresting local changes, if any
git pull

Read the output! If you made local modifications to files tracked in git, it might refuse the update or place conflict markers into the files which need to be resolved. If you run on PostgreSQL and get a message about Gemfile.lock try git checkout Gemfile.lock first. If you get one about db/schema.rb try git checkout db/schema.rb.

In case the recommended Ruby version changed you need to install it. Check with

cd .. && cd -

If that outputs a red warning run the command it gives you and do cd .. && cd - again.

Now we need to update the Ruby libraries:

gem install bundler
bin/bundle # Or DB=postgres bin/bundle for PostgreSQL users
NoteNote:Ignore any migration notes this command gives you, they're already done for you or explicitly advised in our changelog!

Then we apply updates to the database schema, attention this might take some time if you have a big database already:

RAILS_ENV=production bin/rake db:migrate # As always add DB=postgres to the command if you're a PostgreSQL user

Update the static content:

RAILS_ENV=production bin/rake assets:precompile

Make sure to check new configuration options in diaspora.yml.example. Tools like diff and vimdiff can help transfering new sections.

Now you need to restart Diaspora. To do this with the standard startup method you need to get to the place where you run ./script/server, hit Ctrl+C, open a new shell, and run it again.

Updating diaspora* 0.4 to diaspora* 0.5

Since there are a couple of major changes in upgrading to 0.5 which involve manual action, we provide a step by step guide. Please ensure to update to diaspora* 0.4 prior these steps.

NoteNote:This update will take from half an hour up to several hours, as it contains a long running migration, especially on MySQL/MariaDB.
NoteNote:If, and only if, you were testing the release candidate, skip this guide, run git checkout master && git pull and proceed with the normal update instructions below.
  1. Make a backup of at least the database.
  2. Take down diaspora*.
  3. If you're on PostgreSQL run export DB=postgres RAILS_ENV=production, if you're on MySQL/MariaDB run export DB=mysql RAILS_ENV=production. If you encounter a rake aborted! NameError: uninitialized constant Rack::SSL in the rest of this guide, that means you didn't execute this step correctly.
  4. Run bundle exec sidekiq, wait 5 minutes and take it down again with Ctrl+C.
  5. If you modified public/default.html, public/404.html, public/422.html or public/500.html take a backup of the changes, they will be gone or overwritten. Run git checkout Gemfile.lock db/schema.rb public/*.html. Run git stash to preserve any other uncommitted changes. You can later restore stashed changes with git stash pop.
  6. Update RVM with rvm get stable. Install Ruby 2.1 with rvm install 2.1.
  7. Update diaspora with git pull.
  8. Activate the new Ruby with cd .. && cd -.
  9. Install the latest Bundler with gem install bundler.
  10. Install the dependencies with bin/bundle install --without development test. CAREFUL: Do not run any commands that are suggested at the end of this step, that was already done for you.
  11. Verify you didn't run any additional commands already done for you : run git status and delete any untracked files residing in db/migrate.
  12. Edit config/initializers/secret_token.rb, replace secret_token with secret_key_base:
    # Old
    Rails.application.config.secret_token = '***********...'
    
    # New
    Diaspora::Application.config.secret_key_base = '*************...'
    
  13. If you're using MySQL/MariaDB, edit config/database.yml: Replace charset: utf8 with encoding: utf8mb4, notice how the key changed! Replace collation: utf8_bin with collation: utf8mb4_bin. Have a look at the updated config/database.yml.example if you need additional guidance in this step.
  14. Run bin/rake db:migrate, this will take quite a while but you should occasionally check if it failed and seek assistance if it happened to fail.
  15. Run bin/rake tmp:cache:clear assets:precompile. This steps now generates public/404.html, public/422.html and public/500.html.
  16. You can now start diaspora* again as you're used to.

You should now compare your config/diaspora.yml to the updated config/diaspora.yml.example, for example with vimdiff. Notable changes, not only limited to the configuration, are:

  • The surrounding markup for the custom splash page changed slightly, please refer to the changelog.
  • If you're using Paypal donations, the settings in diaspora.yml for it changed, in order to support the unhosted button. Please take a look at the updated diaspora.yml.example.
  • The default for including jQuery from a CDN has changed. If you want to continue to include it from a CDN, please explicitly set the jquery_cdn setting to true in diaspora.yml.
  • There's a new feature to automatically prune inactive accounts, if you want to enable it please refer to the changelog.
  • There's a new feature to proxy embedded images from external sources through your server, strengthening your users privacy. If you want to enable it please refer to Camo.
  • diaspora* 0.5 includes a preview of the new chat feature, if you want to play with it, have a look at Vines. We do not generally recommend enabling this yet.

Updating a development install

Just checkout the develop branch, pull (from upstream), rebundle and migrate the database:

cd diaspora
git checkout develop
git pull # Or git pull upstream develop if you cloned from your fork
cd .. && cd -
bin/bundle # Or DB=postgres bin/bundle if you use PostgreSQL
bin/rake db:migrate