Administration

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

Running your own server needs the Full Version + Server license.

Desktop app users: This page covers server administration tasks. If you are using the desktop app without a server, you do not need any of this - user accounts and data storage are handled automatically. In the full version you can export all your patterns at any time from Backup All on the Saved Patterns page, or from Settings → Account → Data → Export All Patterns. That export holds your patterns, not your thread inventory or settings.

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

Command	Description
`create`	Create a new user account. Prompts for username, email, and password (with confirmation) interactively. The email field is required and must contain '@'.
`list`	List all user accounts. Shows ID, Username, Email, Active (yes/no), Admin (yes/no), and Last Login for each account.
`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.
`admin`	Toggle admin status for a user. Prompts for the username. If the user is not an admin, they are promoted. If they already are, they are demoted, so running it twice undoes it.
`delete`	Delete a user account. Prompts for the username and asks you to type `yes` to confirm. This only removes the account itself. The user's patterns, inventory, and other data stay in the database. To remove a user and everything that belongs to them, use the web admin panel instead.
`tokens`	List every API token on the server, for all users. Shows each token's ID, the user it belongs to, its name, when it was created, and when it was last used.
`revoke`	Revoke one API token. Prompts for the token ID, which you can find with `tokens`.

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

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

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 shield icon in the top bar, and a Manage Users button on the Settings page. Either one 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
Back up and restore - download a ZIP of the database and uploaded images, or restore from one (up to 500 MB)

You cannot delete your own account from the panel, and you cannot delete or demote the last admin.

The web admin panel covers the same user management 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. It is also the better way to delete a user, because it removes their data along with the account.

New users are asked to accept the license agreement the first time they sign in.

Backups

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

In-App Backup Export

You can back up the whole server without command-line access. In the web admin panel, click Download Backup under Backup & Restore. You get a ZIP with the database and uploaded images. To put it back, choose the ZIP under Restore from Backup and click Restore.

Each user can also export their own patterns from Backup All on the Saved Patterns page, or from Settings → Account → Data → Export All Patterns. That export holds patterns only, not thread inventory or settings, and it is part of the full version.

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 Compose adds your project's folder name to the front of the volume name, so find the real name first:
```
docker volume ls | grep needlework-data
docker volume rm <the-name-from-the-list>
```

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`	`6850`	The port the application listens on. Change this if port 6850 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`, sends the HSTS header, and redirects plain http requests to https (unless `TRUST_PROXY` is set to false). It also becomes the default for `TRUST_PROXY`.
`ACCEPT_EULA`	`false`	Required. Set to `true` to accept the license agreement. The Docker container will not start without it.
`LICENSE_KEY`	unset	Required. Your Full Version + Server license key. The server will not start without a valid one. At startup it checks the key with the license server. If it cannot reach the license server it still starts, but a revoked or unknown key stops it from starting.
`SELF_TLS`	`true`	Docker only. When left on, the container serves HTTPS with a certificate it makes for itself, and prints a pairing code at startup. Set to `false` to serve plain http with no certificate. `HTTPS=true` takes priority over this.
`TRUST_PROXY`	same as `HTTPS`	Whether to trust the `X-Forwarded-*` headers a reverse proxy adds. Only turn it on when a proxy you control is actually in front of the app. Set it explicitly if a proxy terminates TLS but `HTTPS` is false.
`TRUSTED_HOSTS`	unset	Optional comma-separated list of the names and addresses you reach the server by. When set, requests for any other host (except localhost) are refused. These names also go into the server's own certificate, so set it before the first start.
`SENTRY_DSN`	unset	Crash reporting. It is off on a server unless you set this to your own Sentry address.
`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.
`ADMIN_USERNAME`	unset	If set, automatically promotes this username to admin on server startup. Useful for initial setup in Docker deployments where you want to avoid running CLI commands inside the container.

Setting Variables with Docker Compose

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

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

volumes:
  needlework-data: