Skip to main content

​
System Requirements

Before installing Tattoo Studio Manager, ensure your system meets the following requirements:

Python

Python 3.11 or higher

Operating System

Windows, macOS, or Linux

RAM

Minimum 4GB RAM

Storage

At least 500MB free space

​
Dependencies

Tattoo Studio Manager relies on the following key dependencies:

​
Core Runtime Dependencies

requirements.txt
PyQt5>=5.15,<6              # Desktop GUI framework
PyQtChart>=5.15.4           # Charts and visualization
SQLAlchemy>=2.0,<3          # Database ORM
alembic>=1.13,<2            # Database migrations
python-dotenv>=1.0,<2       # Environment configuration
Faker>=25,<26               # Test data generation
bcrypt>=4.1.3               # Password hashing

​
Development Dependencies

pytest>=8,<9                # Testing framework
pytest-cov>=5,<6            # Code coverage
black>=24,<25               # Code formatting
isort>=5.13,<6              # Import sorting
flake8>=7,<8                # Code linting
The application uses SQLite as its database, which requires no additional installation.

​
Installation Steps

1

Clone or Download the Source Code

Download the Tattoo Studio Manager source code to your local machine:
cd /path/to/TattoStudio
2

Create a Virtual Environment

Create and activate a Python virtual environment:
python -m venv .venv
.venv\Scripts\activate.bat
Using a virtual environment is highly recommended to isolate dependencies and avoid conflicts with other Python projects.
3

Install Dependencies

Install all required packages using pip:
pip install -r requirements.txt
This will install all runtime and development dependencies listed in requirements.txt.
4

Initialize the Database

The application automatically creates the database on first run. The database file location depends on your environment:
  • Development: dev.db in the project root directory
  • Production (PyInstaller): %APPDATA%\InkLinkOS\inklink.db (Windows)
To populate the database with sample data for testing:
python -m data.tools.seed
This creates:
  • 40 sample clients
  • 4 sample artists (Dylan Bourjac, Jesus Esquer, Pablo Velasquez, Alex Chavez)
  • 3 sample products (Tinta Negra, Guantes, Agujas 5RL)
  • 60 sample tattoo sessions
  • Test users:
    • admin / admin123 (Administrator)
    • assistant / assistant123 (Assistant)
    • jesus / tattoo123 (Artist)
5

Launch the Application

Start the application:
start.bat
The application will launch and display the login screen.

​
Database Configuration

​
Default Database Location

The application automatically determines the database location:
data/db/session.py
def _compute_db_path() -> str:
    # 1) Override with environment variable
    env = os.getenv("DB_PATH")
    if env:
        return str(Path(env).expanduser().resolve())

    # 2) Production: %APPDATA%\InkLinkOS\inklink.db
    if getattr(sys, "frozen", False):
        appdata = os.getenv("APPDATA")
        base_dir = Path(appdata) / "InkLinkOS"
        base_dir.mkdir(parents=True, exist_ok=True)
        return str(base_dir / "inklink.db")

    # 3) Development: dev.db in project root
    project_root = Path(__file__).resolve().parents[2]
    return str(project_root / "dev.db")

​
Custom Database Path

To use a custom database location, set the DB_PATH environment variable: 
export DB_PATH=/path/to/custom/database.db  # macOS/Linux
set DB_PATH=C:\path\to\custom\database.db   # Windows

​
First-Time Configuration

When you launch the application for the first time without any users, the First Run Wizard automatically appears:
1

Studio Setup

Configure your studio information:
  • Studio name
  • Studio logo (optional)
  • Phone number
  • City/Location
2

Admin Account Creation

Create your administrator account:
  • Username
  • Password (securely hashed with bcrypt)
  • Full name
  • Email and contact information
3

Complete Setup

The wizard will:
  • Save your studio configuration to settings.json
  • Create the admin user in the database
  • Initialize the application with your settings
The first admin account has full system access. Choose a strong password and keep credentials secure.

​
Folder Structure

After installation, the application creates the following structure: 
TattoStudio/
├── main.py                 # Application entry point
├── requirements.txt        # Python dependencies
├── dev.db                  # SQLite database (development)
├── settings.json           # Application settings
├── data/                   # Data layer
│   ├── db/                # Database configuration
│   ├── models/            # SQLAlchemy models
│   └── tools/             # Database utilities & migrations
├── ui/                     # User interface
│   ├── pages/             # Application pages
│   ├── widgets/           # Reusable UI components
│   └── styles/            # Theme and styling
├── services/              # Business logic
├── assets/                # Images and icons
├── backups/               # Automatic database backups
└── uploads/               # User-uploaded files
    └── studio/            # Studio logo and assets

​
Troubleshooting

If PyQt5 fails to install, try:
pip install --upgrade pip
pip install PyQt5 --no-cache-dir
On Linux, you may need to install system dependencies:
sudo apt-get install python3-pyqt5
Ensure the application has write permissions to:
  • Project root directory (for dev.db)
  • %APPDATA%\InkLinkOS (Windows production)
  • Backup directory
On Unix systems:
chmod 755 /path/to/TattoStudio
If you encounter import errors:
  1. Verify virtual environment is activated
  2. Reinstall dependencies:
pip install -r requirements.txt --force-reinstall
Check for errors by running:
python main.py
Common issues:
  • Missing dependencies: reinstall from requirements.txt
  • Database corruption: restore from backup or delete dev.db to recreate
  • Python version: ensure Python 3.11 or higher

​
Next Steps

Quick Start Guide

Learn how to use the application for the first time

First-Time Setup

Complete the initial configuration wizard

Database Backups

Configure automatic backups for data protection

User Roles

Learn about admin, assistant, and artist roles

Build docs developers (and LLMs) love

Get started for freeTalk to us