Administration

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

User Management

All user management is handled through the manage_users.py command-line script. This script must be run on the server (or inside the Docker container) and provides the following commands:

Available Commands

Command	Description
`create`	Create a new user account. Prompts for username and password interactively.
`list`	List all user accounts with their status (enabled or disabled).
`password`	Reset a user's password. Prompts for the username and a new password.
`toggle`	Enable or disable a user account. Disabled users cannot log in but their data is preserved.
`delete`	Permanently delete a user account and all associated data.
`tokens`	List all API tokens for a given user.
`revoke`	Revoke a specific API token by its ID.

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 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 delete
docker compose exec needlework-studio python3 manage_users.py tokens
docker compose exec needlework-studio python3 manage_users.py revoke <token-id>

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:

Stop the running container:
```
docker compose down
```
Remove the existing data volume:
```
docker volume rm needlework-data
```

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

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.

Variable	Default	Description
`PORT`	`6969`	The port the application listens on. Change this if port 6969 conflicts with another service on your host.
`SECRET_KEY`	auto-generated	The secret key used to encrypt user sessions. A random key is generated and persisted to disk on first run. You can override it with your own value if needed, but the auto-generated key is secure and sufficient for most deployments.
`HTTPS`	`false`	Set to `true` when running behind an SSL-terminating reverse proxy. This marks session cookies as `Secure`, ensuring they are only sent over encrypted connections.
`FLASK_DEBUG`	`0`	Enable Flask debug mode. Set to `1` for development only - this enables auto-reload and detailed error pages. Never enable in production.
`NEEDLEWORK_DATA_DIR`	app directory	Override the default data and database storage location. By default, all data is stored in the application directory. Set this to an absolute path to store data elsewhere (useful for separating application code from persistent storage).
`DESKTOP_MODE`	`false`	Enable auto-login without credentials. This is used internally by the desktop (Electron) app to bypass the login screen. Do not enable this on a server-hosted deployment - it would allow anyone to access the application without authentication.

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
    restart: unless-stopped

volumes:
  needlework-data: