Installation Tutorial

This tutorial provides step-by-step instructions for installing PyArchInit-Mini on your system.

System Requirements

Before installing PyArchInit-Mini, ensure your system meets these requirements:

  • Operating System: Windows 10+, macOS 10.14+, or Linux (Ubuntu 20.04+, Debian 10+, Fedora 32+)

  • Python: Version 3.9, 3.10, 3.11, 3.12, or 3.13

  • RAM: Minimum 4GB (8GB recommended)

  • Disk Space: 500MB for installation plus space for your databases

  • Internet Connection: Required for initial installation

Installation Methods

PyArchInit-Mini can be installed in several ways depending on your needs.

Method 2: Install in Virtual Environment

Using a virtual environment is recommended for development or if you want to isolate the installation.

Step 1: Create Virtual Environment

# Create a directory for your project
mkdir pyarchinit-project
cd pyarchinit-project

# Create virtual environment
python -m venv venv

Step 2: Activate Virtual Environment

On Windows:

venv\\Scripts\\activate

On macOS/Linux:

source venv/bin/activate

Your prompt should change to show (venv) at the beginning.

Step 3: Install PyArchInit-Mini

pip install pyarchinit-mini

Step 4: Deactivate (when finished)

To deactivate the virtual environment:

deactivate

Method 3: Install from Source (Developers)

For developers who want the latest features or wish to contribute:

Step 1: Clone Repository

git clone https://github.com/pyarchinit/pyarchinit-mini.git
cd pyarchinit-mini

Step 2: Install in Editable Mode

pip install -e .

This installs the package in “editable” mode, meaning changes to the source code are immediately available.

Step 3: Install Development Dependencies

pip install -e ".[dev]"

Database Setup

PyArchInit-Mini supports both SQLite and PostgreSQL databases.

SQLite Setup (Default)

SQLite requires no additional setup. PyArchInit-Mini will create a database file automatically:

# Create a new SQLite database
pyarchinit-mini-cli create-db --db-type sqlite --db-path ./myproject.db

PostgreSQL Setup

For PostgreSQL, you need a running PostgreSQL server.

Step 1: Install PostgreSQL

Step 2: Create Database

# Connect to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE pyarchinit;
\\q

Step 3: Initialize PyArchInit-Mini Database

pyarchinit-mini-cli create-db \\
  --db-type postgresql \\
  --host localhost \\
  --port 5432 \\
  --database pyarchinit \\
  --username your_username \\
  --password your_password

Creating Your First Database

Let’s create a sample database to get started.

Step 1: Create Database File

pyarchinit-mini-cli create-db \\
  --db-type sqlite \\
  --db-path ./tutorial.db

Step 2: Set Database Path

Set the environment variable to use this database:

On Windows:

set DATABASE_URL=sqlite:///tutorial.db

On macOS/Linux:

export DATABASE_URL=sqlite:///tutorial.db

Step 3: Create Admin User

pyarchinit-mini-cli create-user \\
  --username admin \\
  --password your_secure_password \\
  --email admin@example.com \\
  --role admin

Starting the Application

Web Interface

Start the web interface:

pyarchinit-mini-web

The server will start on http://localhost:5001

Open your browser and navigate to that address to access the interface.

Desktop GUI

Start the desktop application:

pyarchinit-mini-gui

The graphical interface will open in a new window.

Common Installation Issues

Issue: “pip: command not found”

Solution: Ensure Python is installed and added to your system PATH. Try:

  • Windows: Reinstall Python and check “Add Python to PATH” during installation

  • macOS: Use python3 -m pip instead of pip

  • Linux: Install pip separately: sudo apt install python3-pip

Issue: Permission Denied Errors

Solution:

On Windows (run as administrator):

pip install --user pyarchinit-mini

On macOS/Linux:

pip3 install --user pyarchinit-mini

Do NOT use sudo pip install as this can cause permission issues.

Issue: Module Not Found Errors

Solution: Ensure you’re using the same Python version that you used for installation:

python3 -m pyarchinit_mini --version

Issue: Database Connection Errors

Solution:

  • Verify the DATABASE_URL environment variable is set correctly

  • Check that the database file exists and is readable

  • For PostgreSQL, ensure the server is running: pg_ctl status

Updating PyArchInit-Mini

To update to the latest version:

pip install --upgrade pyarchinit-mini

Check the changelog for breaking changes:

pyarchinit-mini-cli changelog

Uninstalling

To remove PyArchInit-Mini:

pip uninstall pyarchinit-mini

Your databases and data files are NOT removed automatically. To remove them:

  • Find your database files (usually in the current directory or ~/.pyarchinit/)

  • Delete the database files manually

  • On Linux/macOS: rm -rf ~/.pyarchinit/

  • On Windows: Delete the .pyarchinit folder in your user directory

Next Steps

Now that PyArchInit-Mini is installed:

  1. Start the Web Interface and explore the features

  2. Follow the Web Interface Tutorial to learn the basics

  3. Create your first site and add stratigraphic data

  4. Read the User Guide for detailed documentation

See also

Getting Help

If you encounter issues: