diff --git a/debian/README.Debian b/debian/README.Debian
index bb1079435c..1fb63e7d67 100644
--- a/debian/README.Debian
+++ b/debian/README.Debian
@@ -39,3 +39,77 @@ links are added to enable write access to gitlab app
 > tmp -> /run/gitlab
 > shared/cache -> /var/lib/gitlab/cache
 > /usr/share/gitlab/.secret -> /var/lib/gitlab/.secret
+
+Useful diagnostics
+==================
+
+Upstream documentation will instruct to run commands like the following:
+
+    $ sudo -u gitlab -H bundle exec rake XXX RAILS_ENV=production
+
+Where is something like "db:migrate", "gitlab:check" or "gitlab:env:info". In
+Debian, the rake command has to be called by the gitlab user from its home
+directory /usr/share/gitlab and with the environment variables from
+/etc/gitlab/gitlab-debian.conf set. So above command could be run like:
+
+    # su gitlab
+    $ cd /usr/share/gitlab
+    $ export $(cat /etc/gitlab/gitlab-debian.conf | xargs)
+    $ rake XXX RAILS_ENV=production
+
+One useful command to run in this environment is:
+
+    $ rake gitlab:check RAILS_ENV=production
+
+Which will output helpful diagnostics about the state of your system including
+how to fix possible problems. Another one is:
+
+    $ rake gitlab:env:info RAILS_ENV=production
+
+To see service status with systemd, you can use:
+
+    $ systemctl status gitlab.target
+    $ systemctl status gitlab-unicorn.service -l
+    $ systemctl status gitlab-sidekiq.service -l
+    $ systemctl status gitlab-workhorse.service -l
+    $ journalctl -xn
+
+It is advised to attach the output of above commands to bugreports.
+
+Migrating from non-Debian gitlab
+================================
+
+ 0. Backup everything you don't want to loose like:
+      - the postgresql database used by your gitlab instance
+      - the repositories/ directory
+      - the public/uploads/ directory
+      - your .ssh/authorized_keys
+ 1. Rename your old database to gitlab_production and set the user gitlab as
+    its owner and the owner of all its tables, sequences and views
+ 2. Copy your old repository directory to /var/lib/gitlab/repositories/
+ 3. Copy your old public/uploads/ directory to /usr/share/gitlab/public/uploads/
+ 4. Copy your old .ssh/authorized_keys to /usr/share/gitlab/.ssh/authorized_keys
+    and change the paths to gitlab-shell in your new copy of
+    .ssh/authorized_keys to /usr/share/gitlab-shell/bin/gitlab-shell
+ 5. Start gitlab using `systemctl start gitlab.target`
+ 6. Check the status of your installation using gitlab:check (see section
+    above). The output of that command will tell you the necessary remaining
+    fixes. You might be told to run:
+
+       $ sudo chmod -R ug+rwX,o-rwx /var/lib/gitlab/repositories/
+       $ sudo -u gitlab -H /usr/share/gitlab-shell/bin/create-hooks
+       $ sudo -u gitlab -H bundle exec rake db:migrate RAILS_ENV=production
+
+    See the last section of how to execute the db:migrate command.
+
+Resetting admin password without web interface
+==============================================
+
+    # su gitlab
+    $ cd /usr/share/gitlab
+    $ export $(cat /etc/gitlab/gitlab-debian.conf | xargs)
+    $ rails console production
+    irb(main):001:0> user = User.where(admin: true).first
+    irb(main):002:0> user.password = 'secret_pass'
+    irb(main):003:0> user.password_confirmation = 'secret_pass'
+    irb(main):004:0> user.save!
diff --git a/debian/changelog b/debian/changelog
index 3c7437dbbb..aea723f644 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,6 +1,10 @@
 gitlab (8.4.3+dfsg-11) UNRELEASED; urgency=medium
 
-  * Relax stable library versions requirement 
+  * Relax stable library versions requirement
+
+  [ Johannes Schauer ]
+  * Add diagnostic info to README.Debian
+  * Add steps of migrating a source install to debian package
 
  -- Pirate Praveen <praveen@debian.org>  Wed, 16 Mar 2016 19:23:41 +0530