Revamped post-install and post-upgrade instructions.

1 files changed, 79 insertions, 91 deletions

diff --git a/sentry.install b/sentry.install
index 85278f52bc6f..4dfd7cd9da2b 100644
--- a/sentry.install
+++ b/sentry.install
@@ -5,7 +5,6 @@ post_install(){
     /usr/bin/chown -R root:root /opt/sentry
     /usr/bin/chown -R sentry:sentry /opt/sentry/.python-eggs
     /usr/bin/chown -R sentry:sentry /etc/sentry
-    /usr/bin/chown root:root /etc/sentry
 
     # Storage location for Celery's database.
     /usr/bin/mkdir -p /opt/sentry/celery
@@ -17,63 +16,61 @@ post_install(){
     fi
 
     /usr/bin/chmod 0600 /etc/sentry/sentry.conf.py
-    
-cat << EOF
 
+cat << EOF
 
-INSTALLING OR UPGRADING
+INSTALLATION STEPS
 
-IF YOU'RE INSTALLING OR UPGRADING SENTRY, you will need to issue the following
-command before starting the server:
+1) Initialize Sentry's configuration:
 
     sudo -u sentry PATH=/opt/sentry/bin:\$PATH \\
-        /opt/sentry/bin/sentry --config=/etc/sentry/sentry.conf.py upgrade
+        /opt/sentry/bin/sentry init /etc/sentry
 
-Be sure to edit the configuration file "/etc/sentry/sentry.conf.py" first!
+Be sure to edit the configurations in /etc/sentry before proceeding to the next
+step.
 
-If you're upgrading Sentry, sometimes it may be necessary to run:
+2) Install the appropriate database packages for your setup:
 
-    sudo systemctl --system daemon-reload
-    
-!!! BACK-UP YOUR SENTRY DATABASE BEFORE UPGRADING !!!
+    # MySQL
+    sudo -u sentry -- /usr/bin/bash -c \\
+    'source /opt/sentry/bin/activate && /opt/sentry/bin/pip install mysql-python'
+
+    # PostgreSQL
+    sudo -u sentry -- /usr/bin/bash -c \\
+    'source /opt/sentry/bin/activate && /opt/sentry/bin/pip install psycopg2'
+
+3) Run migrations:
 
-RUNNING
+    sudo -u sentry PATH=/opt/sentry/bin:\$PATH \\
+        /opt/sentry/bin/sentry --config=/etc/sentry/sentry.conf.py upgrade
 
-If you're starting Sentry for the first time, you'll may want to create at
-least one administrative account. To do so, run the createuser utility:
+4) Create the initial superuser:
 
     sudo -u sentry PATH=/opt/sentry/bin:\$PATH \\
         /opt/sentry/bin/sentry --config=/etc/sentry/sentry.conf.py createuser
 
-and create a "superuser" when prompted.
+5) Start Sentry:
 
-To start sentry, simply run the service (sentry-celery, required by sentry,
-will be started automatically):
+    sudo systemctl start sentry sentry-celery
 
-    sudo systemctl start sentry
-    
-To run Sentry without systemd, such as to test your configuration, use:
+If you wish to run Sentry manually, e.g. to test your configuration:
 
     sudo -u sentry PATH=/opt/sentry/bin:\$PATH \\
         --config=/etc/sentry/sentry.conf.py start
 
 EXTRAS
 
-Neither MySQL nor PostgreSQL support is installed into the Python virtualenv
-when building from the PKGBUILD. If you require either of these, you will
-need to install them manually (but don't forget to change your configuration
-file, /etc/sentry/sentry.conf.py to match!):
+To install additional plugins, you'll need to use Sentry's local copy of pip:
 
-    # MySQL
-    sudo -u sentry -- /usr/bin/bash -c \\
-    'source /opt/sentry/bin/activate && /opt/sentry/bin/pip install mysql-python'
+    sudo -u sentry PATH=/opt/sentry/bin:\$PATH \\
+        /opt/sentry/bin/pip install <package>
 
-    # PostgreSQL
-    sudo -u sentry -- /usr/bin/bash -c \\
-    'source /opt/sentry/bin/activate && /opt/sentry/bin/pip install psycopg2'
+REMOVAL
+
+As of Sentry 7.1.4, this package will no longer remove the Sentry user by
+default. You must perform this step manually.
 
-If you need additional Sentry plugins, you'll need to use Sentry's local copy
-of pip to install them in a manner similar to the one outlined above.
+THANKS
 
 I appreciate the tips and suggestions I've received since converting this
 package to a (mostly) pure virtualenv installation. Please report any issues
@@ -83,11 +80,6 @@ project page:
 https://aur.archlinux.org/packages/sentry/
 https://github.com/zancarius/archlinux-pkgbuilds
 
-REMOVAL
-
-As of Sentry 7.1.4, this package will no longer remove the Sentry user by
-default. You must perform this step manually.
-
 EOF
 }
 
@@ -96,7 +88,6 @@ post_upgrade(){
     /usr/bin/chown -R root:root /opt/sentry
     /usr/bin/chown -R sentry:sentry /etc/sentry
     /usr/bin/chown -R sentry:sentry /opt/sentry/.python-eggs
-    /usr/bin/chown root:root /etc/sentry
 
     # Storage location for Celery's database.
     /usr/bin/mkdir -p /opt/sentry/celery
@@ -106,75 +97,77 @@ post_upgrade(){
 
 cat << EOF
 
-UPGRADING - READ THIS FIRST
+UPGRADE STEPS
 
-If you're upgrading Sentry from any prior version, you will first need to
-stop the Sentry service and then reload systemd (sentry-celery first appeared
-in the Sentry 7.1.4 PKGBUILD; if you're upgrading from previous versions, omit
-it from these steps):
+1) Stop Sentry and its related services (and reload systemd)
 
     sudo systemctl stop sentry sentry-celery
     sudo systemctl --system daemon-reload
 
-to ensure that the new systemd service file has been installed.
+2) If you're upgrading from a Sentry version < 8.0, you'll need to update the
+configuration by hand. Sentry's configuration setup has changed dramatically:
 
-You will also need to upgrade your database schema. To do so, copy and paste
-the following command (WITHOUT Sentry running):
+    sudo -u sentry mkdir /etc/sentry/temp
+    sudo -u sentry /opt/sentry/bin/sentry init /etc/sentry/temp
 
-    sudo -u sentry PATH=/opt/sentry/bin:\$PATH \\
-        /opt/sentry/bin/sentry --config=/etc/sentry/sentry.conf.py upgrade
+    # Optionally edit the old configuration:
+    sudo vimdiff /etc/sentry/sentry.conf.py /etc/sentry/temp/sentry.conf.py
 
-You may need to run this command if you're creating a new installation or
-migrating database servers. Sentry will usually check migrations prior to
-starting, but ideally this step should be performed separately.
+    # Move Sentry's YAML configuration to the config root:
+    sudo -u sentry mv /etc/sentry/temp/config.yml /etc/sentry/
 
-Between major (and sometimes minor) version bumps, Sentry's configuration has
-a habit of changing, often introducing new options without which Sentry will
-not launch. As of the Sentry 7.1.4-2 PKGBUILD, Sentry's configuration is
-generated during installation only. You will need to regenerate the
-configuration and check the changes by hand (vimdiff is useful here):
+    # Delete the temporary config directory:
+    sudo rm -r /etc/sentry/temp
 
-    sudo -u sentry /opt/sentry/bin/sentry init /etc/sentry/sentry.conf.new.py
+3) Install the appropriate drivers if you don't already have them (you may skip
+this step if you do):
+
+    # MySQL
+    sudo -u sentry -- /usr/bin/bash -c \\
+    'source /opt/sentry/bin/activate && /opt/sentry/bin/pip install mysql-python'
+
+    # PostgreSQL
+    sudo -u sentry -- /usr/bin/bash -c \\
+    'source /opt/sentry/bin/activate && /opt/sentry/bin/pip install psycopg2'
+
+4) Run the database migrations:
 
 !!! ALWAYS BACK-UP YOUR DATABASE PRIOR TO UPGRADING SENTRY !!!
 
-WARNINGS
+    sudo -u sentry PATH=/opt/sentry/bin:\$PATH \\
+        /opt/sentry/bin/sentry --config=/etc/sentry/sentry.conf.py upgrade
+
+5) Start Sentry:
 
-If you have upgraded to Pacman 4.2 or later, Sentry's installation process
-will generate a large number of permissions- and ownership-related warnings.
-Ignore these. Following Sentry 7.1.4, this package will now correct the
-ownership so subsequent installs will no longer complain.
+    sudo systemctl start sentry sentry-celery
 
-If something happens and Sentry will not run, make sure that 1) you've
-migrated your database schema via Sentry's upgrade process (above) and 2)
-the contents of the /etc/sentry directory are owned by the sentry user.
-Other directories that may need permission tweaks include
-/opt/sentry/.python-eggs and /opt/sentry/celery.
+If you wish to run Sentry manually, e.g. to test your configuration:
+
+    sudo -u sentry PATH=/opt/sentry/bin:\$PATH \\
+        --config=/etc/sentry/sentry.conf.py start
 
 EXTRAS
 
-Neither MySQL nor PostgreSQL support is installed into the Python virtualenv
-when building from the PKGBUILD. If you require either of these, you will
-need to install them manually (but don't forget to change your configuration
-file, /etc/sentry/sentry.conf.py to match!):
+To install additional plugins, you'll need to use Sentry's local copy of pip:
 
-    # MySQL
-    sudo -u sentry -- /usr/bin/bash -c \\
-    'source /opt/sentry/bin/activate && /opt/sentry/bin/pip install mysql-python'
+    sudo -u sentry PATH=/opt/sentry/bin:\$PATH \\
+        /opt/sentry/bin/pip install <package>
 
-    # PostgreSQL
-    sudo -u sentry -- /usr/bin/bash -c \\
-    'source /opt/sentry/bin/activate && /opt/sentry/bin/pip install psycopg2'
+REMOVAL
+
+As of Sentry 7.1.4, this package will no longer remove the Sentry user by
+default. You must perform this step manually.
 
-If you need additional Sentry plugins, you'll need to use Sentry's local copy
-of pip to install them in a manner similar to the one outlined above.
+SENTRY WON'T START?
 
-The Celery backend and task queue is now installed as a separate service
-and is no longer managed by Sentry. This is started via the sentry-celery
-systemd service and requires some configuration before it will work. For a
-basic setup to get started quickly, you'll need to uncomment the variables
-CELERY_ALWAYS_EAGER and BROKER_URL in /etc/sentry/sentry.conf.py. This also
-implies that Sentry now REQUIRES Redis as a dependency.
+Recent versions of Sentry included a configuration for specifying large integers
+for certain ID columns, most notably sentry_project.id. If your migrations fail
+and SENTRY_USE_BIG_INTS is enabled, try disabling it and restart the migration.
+While this is unlikely to bite you unless you've migrated from a much earlier
+version of Sentry (version 6 or early 7), it is one of the most likely blockers
+that may prevent you from updating.
+
+THANKS
 
 I appreciate the tips and suggestions I've received since converting this
 package to a (mostly) pure virtualenv installation. Please report any issues
@@ -184,11 +177,6 @@ project page:
 https://aur.archlinux.org/packages/sentry/
 https://github.com/zancarius/archlinux-pkgbuilds
 
-REMOVAL
-
-As of Sentry 7.1.4, this package will no longer remove the Sentry user by
-default. You must perform this step manually.
-
 EOF
 
 }
\ No newline at end of file