Initialize a Project

Initialize a MSNoise Project

This script initialises a new MSNoise project in the current directory. It creates the db.ini connection file and sets up all database tables with their default configuration values.

Run it once per project with:

msnoise db init

Important

Always run msnoise db init (and all subsequent msnoise commands) from inside the project folder — MSNoise looks for db.ini there.

Prerequisites — MSNoiseDB (recommended)

The easiest way to get a database running is MSNoiseDB, a self-contained PostgreSQL server that requires no system privileges or server administration.

Install it once:

pip install msnoisedb

Then, from its own dedicated folder (not your project folder):

mkdir ~/msnoisedb
cd ~/msnoisedb
msnoisedb start

Important

MSNoiseDB stores the PostgreSQL cluster files in the directory where it is started. Always start it from the same folder. Starting from a different directory creates a new, empty cluster there instead.

The server prints its connection details on startup:

MSNoiseDB started.
Host : localhost
Port : 5099

Keep this terminal open (or background the process) while MSNoise is running. To stop the server:

cd ~/msnoisedb
msnoisedb stop

Create a database for this project

Each project needs its own PostgreSQL database. Create one with:

msnoisedb create-db msnoise_myproject

Replace msnoise_myproject with any name you like. Verify it exists:

msnoisedb list-db

This step is needed once per project — the database persists inside ~/msnoisedb/ across server restarts.

Initialise the project

Create and enter a fresh project folder, then run the initialiser:

mkdir ~/my_msnoise_project
cd ~/my_msnoise_project
msnoise db init

The script asks a few questions. For a typical MSNoiseDB setup:

What database technology do you want to use?
 [1] sqlite
 [2] mysql
 [3] postgresql
Choice: 3
Hostname [localhost:5099] (hostname or hostname:port, e.g. localhost:5099 for MSNoiseDB): localhost:5099
Database name [msnoise]: msnoise_myproject
Username [msnoise]: msnoise
Password: msnoise

MSNoiseDB creates the msnoise user with password msnoise by default — this is intentional for a local, single-user convenience server.

Warning

The credentials are saved in plain text in db.ini in the project folder. Keep this file private if your server is network-accessible.

Quick-start summary

# 1. Start MSNoiseDB (from its own folder, every time)
cd ~/msnoisedb && msnoisedb start

# 2. Create a database for this project (once only)
msnoisedb create-db msnoise_myproject

# 3. Create the project folder and initialise
mkdir ~/my_msnoise_project && cd ~/my_msnoise_project
msnoise db init
# → postgresql | localhost:5099 | msnoise_myproject | msnoise / msnoise

# 4. Open the configurator
msnoise admin

Alternative backends

SQLite (no server, single worker only):

When prompted, choose sqlite. MSNoise creates a .sqlite file in the current folder — no msnoisedb create-db step needed.

Warning

SQLite does not support concurrent writes. Running more than one worker (msnoise -t 2 cc compute) will cause database lock errors. Use PostgreSQL via MSNoiseDB for any real processing.

Self-managed MySQL / MariaDB or PostgreSQL:

Create an empty database on your server first, then provide the host, database name, user and password when prompted. See About Databases and Performances for guidance on when a dedicated server is worth the extra setup.

After initialisation

Launch the web configurator to set project parameters before processing:

msnoise admin

This opens http://localhost:5000 where you can configure dates, archive paths, filters, preprocessing parameters, and moving-stack windows.

See MSNoise Admin (Web Interface) for a tour of the admin interface, and Initialize a Project to continue with the next steps.

What the initialiser does

Writes db.ini with the database connection string.
Creates all MSNoise tables (Config, Station, Job, WorkflowStep, WorkflowLink, …) in the database.
Populates Config with default values from the built-in CSV files.
Creates the default workflow steps and links (the processing DAG).
Creates the default DataSource record (local SDS archive, id=1).

Running msnoise db init again in the same folder updates db.ini but leaves existing tables and data intact.