Administration

Manage users, back up your data, and configure the application through environment variables.

Some features on this page require the Full Version.

User Management

User management can be performed through the manage_users.py command-line script or the web admin panel. The CLI script must be run on the server (or inside the Docker container) and provides the following commands:

Initial Setup

After installing Needlework Studio, create your first user account and promote it to admin:

python manage_users.py create    # create account (username, email, password)
python manage_users.py admin     # promote to admin

For Docker deployments:

docker compose exec needlework-studio python manage_users.py create
docker compose exec needlework-studio python manage_users.py admin

Alternatively, you can set the ADMIN_USERNAME environment variable in your docker-compose.yml to automatically promote a user to admin on server startup:

environment:
  - ADMIN_USERNAME=your_username

Available Commands

Usage Examples

For a manual (non-Docker) installation, run commands directly:

python3 manage_users.py create
python3 manage_users.py list
python3 manage_users.py password
python3 manage_users.py toggle
python3 manage_users.py admin
python3 manage_users.py delete
python3 manage_users.py tokens
python3 manage_users.py revoke <token-id>

Docker Usage

When running inside Docker, prefix every command with docker compose exec:

docker compose exec needlework-studio python3 manage_users.py create
docker compose exec needlework-studio python3 manage_users.py list
docker compose exec needlework-studio python3 manage_users.py password
docker compose exec needlework-studio python3 manage_users.py toggle
docker compose exec needlework-studio python3 manage_users.py admin
docker compose exec needlework-studio python3 manage_users.py delete
docker compose exec needlework-studio python3 manage_users.py tokens
docker compose exec needlework-studio python3 manage_users.py revoke <token-id>

Web Admin Panel

Needlework Studio includes a browser-based admin panel at /admin that provides an alternative to the command-line interface for user management.

Accessing the Admin Panel

Users with admin privileges will see a Manage Users link on the Settings page. Clicking this link opens the admin panel.

Features

The admin panel displays a table of all registered users showing their username, email, account status, and last login date. From this panel, administrators can:

• Create new users - add accounts directly from the browser
• Reset passwords - set a new password for any user
• Enable or disable accounts - toggle whether a user can log in
• Grant or revoke admin privileges - control who has access to the admin panel
• Delete users - permanently remove a user account and all associated data

The web admin panel provides the same user management capabilities as the CLI, making it convenient for administrators who prefer not to use the command line or do not have SSH access to the server.

Backups

Needlework Studio stores all data - the SQLite database, uploaded images, and generated files - in a single directory.

In-App Backup Export

You can export a backup of your data directly from the application without needing command-line access. Open the backup option from the application menu to download an archive of your patterns, thread inventory, and settings. This is the simplest way to create a backup and does not require SSH or Docker access.

Data Locations

• Docker: /data inside the container (mapped to the needlework-data volume).
• Manual install: The application directory itself, or the path specified by the NEEDLEWORK_DATA_DIR environment variable.

Docker Backup

Create a compressed archive of the entire data directory from a running container:

docker compose exec needlework-studio tar czf - /data > needlework-backup-$(date +%F).tar.gz

This produces a timestamped file such as needlework-backup-2025-06-15.tar.gz in your current directory.

Docker Restore

To restore from a backup archive:

1. Stop the running container:

   docker compose down

2. Remove the existing data volume:

   docker volume rm needlework-data

3. Recreate the volume and start a temporary container to extract the backup:

   docker compose up -d
   docker compose exec -T needlework-studio tar xzf - -C / < needlework-backup-2025-06-15.tar.gz

4. Restart the container to pick up the restored data:

   docker compose restart

Manual Backup

For non-Docker installations, copy the data directory (or the entire application directory if NEEDLEWORK_DATA_DIR is not set) to a safe location:

tar czf needlework-backup-$(date +%F).tar.gz /path/to/needlework/data

Consider scheduling regular backups with a cron job to avoid data loss.

Environment Variables

Needlework Studio is configured through environment variables. Set these in your shell, a .env file alongside your docker-compose.yml, or your system's service manager configuration.

Setting Variables with Docker Compose

Add an environment section to your docker-compose.yml:

services:
  needlework-studio:
    image: ghcr.io/greenglasst/needleworkstudio:latest
    ports:
      - "6969:6969"
    volumes:
      - needlework-data:/data
    environment:
      - HTTPS=true
      - SECRET_KEY=your-custom-secret-key
      - ADMIN_USERNAME=your_username
    restart: unless-stopped

volumes:
  needlework-data: