Updating a customer-hosted Looker instance

You will be notified of new Looker releases as they become available. We recommend updating Looker regularly to keep current with bug fixes and new features.

If you have a cluster of Looker instances, you must update a single node completely before updating the other instances.

This update process assumes your Looker instance includes the startup script, which should have been installed as part of the initial Looker installation process.

  1. Download the most recent release of the Looker JAR files as described on the Downloading the Looker JAR Files documentation page.
  2. Stop the Looker process from shell, as the looker user:

    sudo su - looker
    cd /home/looker/looker
    ./looker stop
    

    If you are updating a Looker cluster, repeat the process above to stop Looker on every node.

  3. Back up your entire Looker directory, including hidden directories (see the Restoring backups documentation page for more detail).

  4. If you have migrated Looker's default in-memory database to an external MySQL database, or if you are updating a Looker cluster, back up the MySQL database.

  5. Rename looker-x.x.x.jar to looker.jar and looker-dependencies-x.x.x.jar to looker-dependencies.jar. Copy looker.jar and looker-dependencies.jar to the server directory (/home/looker/looker/looker.jar). Both files must be in the same directory.

  6. Start the Looker process from the shell as the looker user:

    If you are updating a Looker cluster, start the Looker process on one node only. Do not start Looker on the other nodes until the first node has completed the update process.

    ./looker start
    

    You can also use the java -jar command to start Looker. The core JAR will find the dependency JAR as long as it is in the ./looker directory along with the core JAR.

    In addition, if you'd rather use a Looker-provided startup script, you can find a startup script at: https://github.com/looker/customer-scripts.

    When you update your Looker version, Looker must also update its internal database. The database update usually takes less than five minutes, but it can sometimes take longer than the Looker startup process. If you try to start Looker while the internal database is still updating, the daemonizing process will time out in six minutes with the message "Timed out waiting for Looker to start."

    During an update, the required migrations can take up to an hour, especially if you are skipping several releases. If you receive this error message, wait for the update to finish and for Looker to start. You can confirm whether the update process is still running by using the command:

    ps -f $(pgrep -f -- '-jar looker.jar')
    

    Stopping and restarting the Looker process while the internal database updates are in progress can corrupt the internal database. If this happens, restore Looker from an existing backup and perform the update again.

  7. If you are updating a Looker cluster, wait until the first node has completed the update process before starting Looker on the other nodes.