Notes on setting up the database

Prerequisites

You must have MySQl or Mariadb installed and running to use IMPS. IMPS cannot install a database server for you -- once that part is done, everything else described below (creating the database, the database user, and IMPS's tables) can be done for you automatically by the in-app setup wizard.

Using the setup wizard (recommended)

The first time you open IMPS in a browser, it will take you to the Welcome to IMPS setup wizard instead of the normal home page. This wizard walks you through everything needed to get a new install running:

  1. If you haven't installed MariaDB yet, the wizard's Install MariaDB (Ubuntu) page has copy-pasteable install commands.
  2. The Database connection page lets you enter your database host, name, username, and password directly in the browser. IMPS tests the connection live and shows you the result before you move on.
  3. If the database is empty, IMPS creates all of the necessary tables for you automatically. If the database already has IMPS-looking tables in it (for example, if you're re-running setup against a database you've used before), the wizard asks whether to keep the existing tables or start fresh, rather than guessing.
  4. You can optionally have the wizard install a small set of sample boxes, categories, and items, so a new install isn't completely empty while you get familiar with IMPS.
  5. Finally, the wizard lets you set the IMPS password (see Troubleshooting if you need to change this later).

None of this requires editing imps_config.toml by hand or restarting the server -- the wizard writes your settings to that file for you and reloads them immediately.

Setting up the database manually (alternative)

If you'd rather not use the wizard, you can set up the database yourself using the SQL files included with IMPS.

The deploy/setup.sql file creates the database and a database user with the permissions IMPS needs. While the file has a default username and password provided, you should edit the file to change these to something unique to your IMPS install for security purposes.

The line to edit is:

CREATE USER IF NOT EXISTS 'box_user'@'localhost' IDENTIFIED BY 'box_pass';

Change box_user and box_pass, then use those same values later, either when the setup wizard's Database connection page asks for your credentials, or directly in imps_config.toml if you're skipping the wizard entirely.

Setup database on MySQL / Mariadb

  1. sudo mysql -u root < deploy/setup.sql
  2. mysql -u box_user -p box_db < deploy/schema.sql

Most people are better served by the setup wizard above -- it does the same thing without needing you to run SQL by hand.