studio-console 1.3.4__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- studio_console-1.3.4/.gitignore +48 -0
- studio_console-1.3.4/LEGAL.md +60 -0
- studio_console-1.3.4/LICENSE +112 -0
- studio_console-1.3.4/PKG-INFO +235 -0
- studio_console-1.3.4/README.md +217 -0
- studio_console-1.3.4/VERSION +1 -0
- studio_console-1.3.4/docker-compose.yml +282 -0
- studio_console-1.3.4/install.sh +137 -0
- studio_console-1.3.4/nginx/studio.conf.template +89 -0
- studio_console-1.3.4/pyproject.toml +53 -0
- studio_console-1.3.4/studio-console.py +16 -0
- studio_console-1.3.4/studio_console/__init__.py +17 -0
- studio_console-1.3.4/studio_console/__main__.py +3 -0
- studio_console-1.3.4/studio_console/cli.py +176 -0
- studio_console-1.3.4/studio_console/cloudflare/__init__.py +1 -0
- studio_console-1.3.4/studio_console/cloudflare/cf_api.py +285 -0
- studio_console-1.3.4/studio_console/cloudflare/cf_wizard.py +1549 -0
- studio_console-1.3.4/studio_console/commands.py +3001 -0
- studio_console-1.3.4/studio_console/commands_container.py +526 -0
- studio_console-1.3.4/studio_console/commands_launch.py +684 -0
- studio_console-1.3.4/studio_console/constants.py +184 -0
- studio_console-1.3.4/studio_console/data/README.md +37 -0
- studio_console-1.3.4/studio_console/data/known_baselines.json +3 -0
- studio_console-1.3.4/studio_console/env.py +600 -0
- studio_console-1.3.4/studio_console/major_version.py +257 -0
- studio_console-1.3.4/studio_console/tui.py +412 -0
- studio_console-1.3.4/studio_console/wizard.py +1953 -0
- studio_console-1.3.4/templates/.env.example +76 -0
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Python
|
|
2
|
+
__pycache__/
|
|
3
|
+
*.py[cod]
|
|
4
|
+
*.pyo
|
|
5
|
+
*.pyd
|
|
6
|
+
.Python
|
|
7
|
+
*.egg-info/
|
|
8
|
+
*.egg
|
|
9
|
+
dist/
|
|
10
|
+
build/
|
|
11
|
+
.eggs/
|
|
12
|
+
|
|
13
|
+
# Virtual environments
|
|
14
|
+
.venv/
|
|
15
|
+
venv/
|
|
16
|
+
env/
|
|
17
|
+
|
|
18
|
+
# Distribution / packaging
|
|
19
|
+
*.whl
|
|
20
|
+
*.tar.gz
|
|
21
|
+
MANIFEST
|
|
22
|
+
docs/plans
|
|
23
|
+
|
|
24
|
+
# Tools
|
|
25
|
+
.mypy_cache/
|
|
26
|
+
.ruff_cache/
|
|
27
|
+
.pytest_cache/
|
|
28
|
+
.coverage
|
|
29
|
+
htmlcov/
|
|
30
|
+
|
|
31
|
+
# Editor
|
|
32
|
+
.vscode/
|
|
33
|
+
.idea/
|
|
34
|
+
|
|
35
|
+
# OS
|
|
36
|
+
.DS_Store
|
|
37
|
+
|
|
38
|
+
# Scratch
|
|
39
|
+
CHANGES.diff
|
|
40
|
+
CHANGES.md
|
|
41
|
+
|
|
42
|
+
# Internal seat files, never publish to this repo
|
|
43
|
+
CLAUDE.md
|
|
44
|
+
THINKING.md
|
|
45
|
+
.claude/
|
|
46
|
+
chat-index.md
|
|
47
|
+
# uv test-run artifact
|
|
48
|
+
uv.lock
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
# Studio Console: Operator Responsibilities
|
|
2
|
+
|
|
3
|
+
Console is the operator tool for provisioning, configuring, backing up,
|
|
4
|
+
restoring, upgrading, and managing Studio deployments. The LICENSE defines
|
|
5
|
+
what you may and may not do with Console. This document summarizes the
|
|
6
|
+
practical responsibilities that come with operating it. These notes are
|
|
7
|
+
informational and do not modify the LICENSE; where they conflict, the LICENSE
|
|
8
|
+
governs.
|
|
9
|
+
|
|
10
|
+
## What Console does and does not grant
|
|
11
|
+
|
|
12
|
+
Console is a separate artifact from the Studio platform and from Studio
|
|
13
|
+
Marketplace packages. Installing or using Console does not grant any right in
|
|
14
|
+
Studio or in marketplace content beyond what the Studio Use License and the
|
|
15
|
+
Studio Marketplace Package License independently permit. Console manages a
|
|
16
|
+
deployment; it does not license the software or content that deployment runs.
|
|
17
|
+
|
|
18
|
+
## Permitted operation
|
|
19
|
+
|
|
20
|
+
You may use Console to run and manage your own Studio deployments, and to
|
|
21
|
+
install, configure, and manage deployments for individual clients as part of
|
|
22
|
+
bespoke service engagements. Ongoing management of a client's deployment
|
|
23
|
+
(monitoring, upgrades, backups, support) is permitted.
|
|
24
|
+
|
|
25
|
+
## The provisioning boundary
|
|
26
|
+
|
|
27
|
+
The line is the same one the Studio Use License draws, operating versus
|
|
28
|
+
distributing:
|
|
29
|
+
|
|
30
|
+
- **Permitted:** using Console to stand up and manage deployments, one at a
|
|
31
|
+
time, as part of delivering a solution or service.
|
|
32
|
+
- **Not permitted:** using Console (or a modified or reimplemented version of
|
|
33
|
+
it) as the engine of a service whose primary function is provisioning,
|
|
34
|
+
hosting, or vending Studio instances to third parties, whether offered
|
|
35
|
+
directly, wrapped, or automated.
|
|
36
|
+
|
|
37
|
+
Managing a deployment for a client is a service. Offering "Studio instances
|
|
38
|
+
on demand" to others is a distribution business, and is not permitted.
|
|
39
|
+
|
|
40
|
+
## Operator obligations
|
|
41
|
+
|
|
42
|
+
As the party running Console and the deployments it manages, you are
|
|
43
|
+
responsible for:
|
|
44
|
+
|
|
45
|
+
- Compliance with all applicable laws in your jurisdiction and your
|
|
46
|
+
customers' jurisdictions.
|
|
47
|
+
- Securing the infrastructure Console operates on, including credentials,
|
|
48
|
+
tokens, backups, and any secrets Console reads or writes.
|
|
49
|
+
- The terms of any third-party services, hosting providers, or model
|
|
50
|
+
providers used by the deployments you manage, including their costs,
|
|
51
|
+
usage limits, and data-handling requirements.
|
|
52
|
+
- Any modifications you make to Console and their effects on the deployments
|
|
53
|
+
you manage.
|
|
54
|
+
|
|
55
|
+
## No warranty
|
|
56
|
+
|
|
57
|
+
Console is provided "as is," without warranty of any kind. See the LICENSE
|
|
58
|
+
for the full disclaimer. Backup, restore, upgrade, and provisioning
|
|
59
|
+
operations carry inherent risk; you are responsible for verifying backups and
|
|
60
|
+
testing changes before applying them to production deployments.
|
|
@@ -0,0 +1,112 @@
|
|
|
1
|
+
Studio Console Use License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kawika Ohumukini. All rights reserved.
|
|
4
|
+
|
|
5
|
+
This license governs the use of Studio Console ("Console"), the operator
|
|
6
|
+
command-line tool and its associated components and documentation. Console
|
|
7
|
+
is distributed as a standalone artifact and is licensed separately from the
|
|
8
|
+
Studio platform software, which is governed by its own Studio Use License.
|
|
9
|
+
|
|
10
|
+
This is not an open-source license. The source code is publicly available
|
|
11
|
+
for transparency and community contribution, but commercial use is subject
|
|
12
|
+
to the terms below.
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
1. PERMITTED USE
|
|
16
|
+
|
|
17
|
+
You may:
|
|
18
|
+
|
|
19
|
+
(a) Install and use Console to provision, configure, back up, restore,
|
|
20
|
+
upgrade, scale, and otherwise manage your own Studio deployments.
|
|
21
|
+
|
|
22
|
+
(b) Install and provide Console on a client's infrastructure, and use it to
|
|
23
|
+
install, configure, manage, and provide ongoing management of Studio
|
|
24
|
+
deployments for individual clients as part of bespoke service
|
|
25
|
+
engagements, and to provide consulting, installation, deployment,
|
|
26
|
+
configuration, training, and support services related to Console and to
|
|
27
|
+
Studio. The copying and installation of Console reasonably necessary to
|
|
28
|
+
deliver these services is permitted notwithstanding Section 2.
|
|
29
|
+
|
|
30
|
+
(c) Modify Console for your own use.
|
|
31
|
+
|
|
32
|
+
(d) Contribute to this project.
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
2. RESTRICTIONS
|
|
36
|
+
|
|
37
|
+
You may not:
|
|
38
|
+
|
|
39
|
+
(a) Use Console, a modified version of Console, or any component derived
|
|
40
|
+
from it, to build, offer, or operate a platform, tool, or service whose
|
|
41
|
+
primary function is the automated or self-service provisioning of Studio
|
|
42
|
+
instances to third parties, or the vending of Studio instances as a
|
|
43
|
+
product. (Delivering managed services for a bespoke client's own
|
|
44
|
+
deployment, as permitted in Section 1(b), is not restricted by this
|
|
45
|
+
paragraph.)
|
|
46
|
+
|
|
47
|
+
(b) Offer automated or self-service provisioning of Studio instances to
|
|
48
|
+
third parties, whether by exposing Console directly, wrapping it, or
|
|
49
|
+
reimplementing its provisioning behavior.
|
|
50
|
+
|
|
51
|
+
(c) Fork or rebrand Console for resale or distribution as a competing
|
|
52
|
+
provisioning, deployment, or management tool or service.
|
|
53
|
+
|
|
54
|
+
(d) Redistribute, sublicense, or sell copies of the Console source code
|
|
55
|
+
as a standalone product or component.
|
|
56
|
+
|
|
57
|
+
(e) Create, distribute, or sell pre-configured images, containers,
|
|
58
|
+
deployment packages, or infrastructure templates that contain or
|
|
59
|
+
install Console for third-party use.
|
|
60
|
+
|
|
61
|
+
(f) Remove or alter any copyright, trademark, or license notices included
|
|
62
|
+
in Console.
|
|
63
|
+
|
|
64
|
+
The distinction this license draws is between OPERATING and DISTRIBUTING.
|
|
65
|
+
You may use Console to run and manage Studio deployments, your own or a
|
|
66
|
+
client's. You may not use Console to build a business that provisions,
|
|
67
|
+
hosts, or distributes Studio deployments as a service to others.
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
3. RELATIONSHIP TO STUDIO AND MARKETPLACE
|
|
71
|
+
|
|
72
|
+
Console is a separate artifact from the Studio platform and from Studio
|
|
73
|
+
Marketplace packages. This license governs Console only. It grants no rights
|
|
74
|
+
in the Studio platform software (see the Studio Use License) or in any
|
|
75
|
+
marketplace package (see the Studio Marketplace Package License). Use of Console
|
|
76
|
+
to manage a deployment does not authorize any use of Studio or marketplace
|
|
77
|
+
content that those terms do not independently permit.
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
4. TRADEMARKS
|
|
81
|
+
|
|
82
|
+
"Studio," "Studio Console," "Self-Host Studio," "Self-Host Hub," and
|
|
83
|
+
associated logos and marks are trademarks of the copyright holder. Use of
|
|
84
|
+
these trademarks is subject to applicable trademark law. You may use these
|
|
85
|
+
names to truthfully describe your relationship with the Software (e.g.,
|
|
86
|
+
"manages Self-Host Studio," "built on Studio Console"). You may not use the
|
|
87
|
+
trademarks in a way that implies endorsement, affiliation, or origin without
|
|
88
|
+
prior written consent. Nothing in this license grants the right to use these
|
|
89
|
+
names or marks as part of a product name, company name, or primary branding.
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
5. CONTRIBUTIONS
|
|
93
|
+
|
|
94
|
+
Contributions to this project are assigned to the copyright holder and their
|
|
95
|
+
successors and assigns. By submitting a contribution, you agree to this
|
|
96
|
+
assignment and represent that you have the right to make the contribution.
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
6. NO WARRANTY
|
|
100
|
+
|
|
101
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
102
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
103
|
+
FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT.
|
|
104
|
+
|
|
105
|
+
IN NO EVENT SHALL THE AUTHORS, COPYRIGHT HOLDERS, OR CONTRIBUTORS BE LIABLE
|
|
106
|
+
FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
|
|
107
|
+
TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE
|
|
108
|
+
OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
109
|
+
|
|
110
|
+
Operators are solely responsible for compliance with applicable laws and
|
|
111
|
+
third-party service terms. See LEGAL.md for operator obligations.
|
|
112
|
+
|
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: studio-console
|
|
3
|
+
Version: 1.3.4
|
|
4
|
+
Summary: Studio operator management console
|
|
5
|
+
Project-URL: Homepage, https://github.com/selfhosthub/studio-console
|
|
6
|
+
Project-URL: Issues, https://github.com/selfhosthub/studio-console/issues
|
|
7
|
+
Author: Kawika Ohumukini
|
|
8
|
+
License-Expression: LicenseRef-Studio-Console-Use-License
|
|
9
|
+
License-File: LEGAL.md
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: console,operator,selfhost,studio
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Requires-Python: >=3.8
|
|
16
|
+
Requires-Dist: cryptography>=41.0
|
|
17
|
+
Description-Content-Type: text/markdown
|
|
18
|
+
|
|
19
|
+
# studio-console
|
|
20
|
+
|
|
21
|
+
Operator CLI for managing a self-hosted [Studio](https://github.com/selfhosthub/studio) instance. Wraps Docker Compose to handle setup, configuration, and day-to-day operations.
|
|
22
|
+
|
|
23
|
+
## Deployment shapes
|
|
24
|
+
|
|
25
|
+
Studio ships three images. Most operators want **Split**.
|
|
26
|
+
|
|
27
|
+
- **Split** — multi-container compose stack. Console runs on the host and manages `docker compose`. **This README documents Split.**
|
|
28
|
+
- **Core** (`studio-core`) — single container bundling API + UI; you bring an external Postgres. Console runs inside the container.
|
|
29
|
+
- **Full** (`studio-full` / `studio-standalone`) — single container with bundled Postgres.
|
|
30
|
+
|
|
31
|
+
In Core and Full the container entrypoint provisions Studio on first boot; the console is a diagnostic + ops tool.
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## Table of Contents
|
|
36
|
+
|
|
37
|
+
- [Quick Start](#quick-start)
|
|
38
|
+
- [Run the Full image](#run-the-full-image)
|
|
39
|
+
- [Daily Operations](#daily-operations)
|
|
40
|
+
- [Upgrading](#upgrading)
|
|
41
|
+
- [CLI Reference](#cli-reference)
|
|
42
|
+
- [Further reading](#further-reading)
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Quick Start
|
|
47
|
+
|
|
48
|
+
[Docker](https://docs.docker.com/get-docker/) + Compose v2 required.
|
|
49
|
+
|
|
50
|
+
### Interactive
|
|
51
|
+
|
|
52
|
+
```sh
|
|
53
|
+
# 1. Install uv (one-time)
|
|
54
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
55
|
+
source ~/.bashrc # macOS default shell is zsh — use ~/.zshrc instead
|
|
56
|
+
|
|
57
|
+
# 2. Install studio-console
|
|
58
|
+
uv tool install https://github.com/selfhosthub/studio-console/releases/download/v1.3.4/studio_console-1.3.4-py3-none-any.whl
|
|
59
|
+
|
|
60
|
+
# 3. Run
|
|
61
|
+
studio-console
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
On first run with no `~/.studio/.env`, the wizard launches. Walk through the sections, save, then go to **Services → Start all**.
|
|
65
|
+
|
|
66
|
+
The wizard creates `~/.studio/` containing `.env` (0600), `docker-compose.yml`, `nginx/studio.conf`, and four data subdirs:
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
~/.studio/
|
|
70
|
+
├── .env, .bootstrapped, docker-compose.yml, nginx/
|
|
71
|
+
├── db/ postgres data (SHS_DB_DATA)
|
|
72
|
+
├── storage/ orgs, uploads, outputs (SHS_STORAGE_ROOT — mounted at /workspace in containers)
|
|
73
|
+
├── models/ model files (SHS_MODELS_ROOT)
|
|
74
|
+
└── backups/ local DB dumps (SHS_BACKUP_ROOT)
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Each data subdir is its own env var, so a cloud deploy can repoint individual roots at CloudSQL, GCS, or a network volume without changing code. **Protect this directory and never delete `.env`** — two of its values cannot be regenerated:
|
|
78
|
+
|
|
79
|
+
- `SHS_CREDENTIAL_ENCRYPTION_KEY` — losing it makes all stored provider API keys unrecoverable.
|
|
80
|
+
- `POSTGRES_PASSWORD` — set on first DB init; the live database keeps using this value, so a regenerated one will lock the API out.
|
|
81
|
+
|
|
82
|
+
Back both up separately (password manager, secrets vault) so you can recover if the host or `.env` is ever lost.
|
|
83
|
+
|
|
84
|
+
### Non-interactive (scripted / CI)
|
|
85
|
+
|
|
86
|
+
```bash
|
|
87
|
+
SHS_CREDENTIAL_ENCRYPTION_KEY=<32+ char key> \
|
|
88
|
+
SHS_ADMIN_EMAIL=admin@example.com \
|
|
89
|
+
SHS_ADMIN_PASSWORD=<password> \
|
|
90
|
+
studio-console init && studio-console start
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Full list of supported environment variables in [docs/env-vars.md](docs/env-vars.md).
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Run the Full image
|
|
98
|
+
|
|
99
|
+
The **Full** image (`studio-full`) is a single self-contained container — bundled Postgres, API, UI, and workers under supervisord. No Compose stack, no external database. `launch-full` runs it on your machine and drops you into its in-container console.
|
|
100
|
+
|
|
101
|
+
```sh
|
|
102
|
+
# Launch (workspace defaults to ~/.studio, shared with Split)
|
|
103
|
+
studio-console launch-full --tag 1.0.0
|
|
104
|
+
|
|
105
|
+
# Use a separate workspace to run Full alongside a Split install
|
|
106
|
+
studio-console launch-full --tag 1.0.0 --workspace ~/.studio-full
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
The workspace (mounted at `/workspace`) holds the generated `.env`, the Postgres data dir, and org files — it persists across restarts. You're prompted once for a supervisor username/password; the console remembers them and re-injects on every launch.
|
|
110
|
+
|
|
111
|
+
> **Do not point Full at an existing Split `~/.studio` workspace** unless you mean to share it. Split and Full share the same `.env`/encryption key but **must never run concurrently** against the same data. Use `--workspace` to keep them separate.
|
|
112
|
+
|
|
113
|
+
### Re-entering the console after you exit
|
|
114
|
+
|
|
115
|
+
Exiting the console **does not stop the container** — it keeps running. `launch-full` won't re-attach to an already-running container; instead, exec back in from the host:
|
|
116
|
+
|
|
117
|
+
```sh
|
|
118
|
+
docker exec -it studio-full studio-console # re-open the in-container menu
|
|
119
|
+
|
|
120
|
+
# Or run one-off commands from the host without entering the menu:
|
|
121
|
+
docker exec studio-full studio-console health
|
|
122
|
+
docker exec studio-full studio-console restart api
|
|
123
|
+
docker exec studio-full studio-console logs api
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Inside the container the console manages services via `supervisorctl` (health, restart, logs, per-service control), plus config, backup, password reset, and Cloudflare setup.
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## Daily Operations
|
|
131
|
+
|
|
132
|
+
```
|
|
133
|
+
Services → Start all bring everything up
|
|
134
|
+
Services → Stop all bring everything down
|
|
135
|
+
Services → Health check API + worker status
|
|
136
|
+
Services → View logs recent logs (all or per-service)
|
|
137
|
+
Services → Stream logs follow live (Ctrl-C to stop)
|
|
138
|
+
Services → Links open UI and API docs in browser
|
|
139
|
+
|
|
140
|
+
Backup → Backup all database + .env + org files
|
|
141
|
+
Backup → Restore DB pick a .sql file from disk
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Backups land in `~/.studio/backups/studio-YYYYMMDD_HHMMSS/`.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Upgrading
|
|
149
|
+
|
|
150
|
+
**Studio (the application):**
|
|
151
|
+
|
|
152
|
+
```
|
|
153
|
+
Images → Upgrade
|
|
154
|
+
```
|
|
155
|
+
|
|
156
|
+
Pulls the latest tag from GHCR, updates `SHS_STUDIO_VERSION` in `.env`, and restarts all services. If the new version's major doesn't match your database's major, the upgrade is blocked with a clear message — see [docs/architecture.md](docs/architecture.md#major-version-boundary-detection).
|
|
157
|
+
|
|
158
|
+
**studio-console itself:**
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
uv tool install --force <new-release-url>
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
Latest release is always at [github.com/selfhosthub/studio-console/releases/latest](https://github.com/selfhosthub/studio-console/releases/latest).
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## Cutting a release
|
|
169
|
+
|
|
170
|
+
**One command. Never tag, bump `VERSION`, or run `gh release` by hand** — the script does all of it (bumps `VERSION`, updates the README install URL, commits, pushes, tags, builds the wheel, publishes the release with the correct title).
|
|
171
|
+
|
|
172
|
+
```bash
|
|
173
|
+
# 1. Land your fix on main first (commit + push as normal).
|
|
174
|
+
# 2. Then cut the release — pick the bump size:
|
|
175
|
+
scripts/release-console.sh patch # bug fix 1.0.0 → 1.0.1
|
|
176
|
+
scripts/release-console.sh minor # new feature 1.0.0 → 1.1.0
|
|
177
|
+
scripts/release-console.sh major # breaking 1.0.0 → 2.0.0
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
Preview without touching anything: add `--dry-run`. Override the notes with `--message "..."`. Re-cut a release you already published (e.g. it shipped before a fix landed): `scripts/release-console.sh <X.Y.Z> --force`.
|
|
181
|
+
|
|
182
|
+
After release, bump the console pin in the Studio versions file to the new version so the next core/full image build bakes it in.
|
|
183
|
+
|
|
184
|
+
---
|
|
185
|
+
|
|
186
|
+
## CLI Reference
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
studio-console # wizard on first run, menu otherwise
|
|
190
|
+
|
|
191
|
+
studio-console start # start all services
|
|
192
|
+
studio-console stop # stop all services
|
|
193
|
+
studio-console restart [service] # restart all or one service
|
|
194
|
+
studio-console health # API + worker health check
|
|
195
|
+
studio-console logs [service] # view recent logs
|
|
196
|
+
studio-console build [image ...] # build images from source
|
|
197
|
+
studio-console upgrade # pull latest version + restart
|
|
198
|
+
studio-console backup # backup database + files
|
|
199
|
+
studio-console restore [path] # restore from backup directory
|
|
200
|
+
studio-console links # print service URLs
|
|
201
|
+
studio-console config # show current .env values
|
|
202
|
+
studio-console config set KEY VALUE # set a single .env value
|
|
203
|
+
studio-console workers # list/scale workers
|
|
204
|
+
studio-console reset-password # reset super admin password
|
|
205
|
+
studio-console wizard # re-run setup wizard
|
|
206
|
+
studio-console init # non-interactive setup from env vars
|
|
207
|
+
studio-console self-update # upgrade studio-console itself
|
|
208
|
+
studio-console version # print version
|
|
209
|
+
|
|
210
|
+
studio-console launch-full [--tag T] [--workspace DIR] # run the Full single-container image on the host
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
For the Full image, run operational subcommands through `docker exec studio-full studio-console <cmd>` — see [Run the Full image](#run-the-full-image).
|
|
214
|
+
|
|
215
|
+
---
|
|
216
|
+
|
|
217
|
+
## Further reading
|
|
218
|
+
|
|
219
|
+
- **[Architecture](docs/architecture.md)** — file layout, state flow, Compose wiring, first-boot, internals (wizard vs init, orphan workers, backup format, major-version detection, deployment contexts).
|
|
220
|
+
- **[Environment variables](docs/env-vars.md)** — every `SHS_*` and supporting var.
|
|
221
|
+
- **[Public hostname topology](docs/topology.md)** — single vs split hostnames, Cloudflare tunnel + Access, IP restrictions.
|
|
222
|
+
- **[VPS + RunPod deployments](docs/vps-runpod.md)** — hybrid setups with GPU worker pods on RunPod.
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## License
|
|
227
|
+
|
|
228
|
+
Studio Console is source-available under the **Studio Console Use License**. It is not open source.
|
|
229
|
+
|
|
230
|
+
You may install, run, and modify Console to manage your own Studio deployments, and to install and manage deployments for individual clients as service work. You may not redistribute, fork, sublicense, or resell it, and you may not use it as the engine of a service that provisions or vends Studio instances to third parties.
|
|
231
|
+
|
|
232
|
+
Console is licensed separately from the Studio platform, which is governed by its own [Studio Use License](https://github.com/selfhosthub/studio/blob/main/LICENSE). Installing Console grants no rights in Studio or in marketplace content.
|
|
233
|
+
|
|
234
|
+
- [LICENSE](LICENSE): the full terms
|
|
235
|
+
- [LEGAL.md](LEGAL.md): operator obligations and third-party responsibilities
|
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
# studio-console
|
|
2
|
+
|
|
3
|
+
Operator CLI for managing a self-hosted [Studio](https://github.com/selfhosthub/studio) instance. Wraps Docker Compose to handle setup, configuration, and day-to-day operations.
|
|
4
|
+
|
|
5
|
+
## Deployment shapes
|
|
6
|
+
|
|
7
|
+
Studio ships three images. Most operators want **Split**.
|
|
8
|
+
|
|
9
|
+
- **Split** — multi-container compose stack. Console runs on the host and manages `docker compose`. **This README documents Split.**
|
|
10
|
+
- **Core** (`studio-core`) — single container bundling API + UI; you bring an external Postgres. Console runs inside the container.
|
|
11
|
+
- **Full** (`studio-full` / `studio-standalone`) — single container with bundled Postgres.
|
|
12
|
+
|
|
13
|
+
In Core and Full the container entrypoint provisions Studio on first boot; the console is a diagnostic + ops tool.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Table of Contents
|
|
18
|
+
|
|
19
|
+
- [Quick Start](#quick-start)
|
|
20
|
+
- [Run the Full image](#run-the-full-image)
|
|
21
|
+
- [Daily Operations](#daily-operations)
|
|
22
|
+
- [Upgrading](#upgrading)
|
|
23
|
+
- [CLI Reference](#cli-reference)
|
|
24
|
+
- [Further reading](#further-reading)
|
|
25
|
+
|
|
26
|
+
---
|
|
27
|
+
|
|
28
|
+
## Quick Start
|
|
29
|
+
|
|
30
|
+
[Docker](https://docs.docker.com/get-docker/) + Compose v2 required.
|
|
31
|
+
|
|
32
|
+
### Interactive
|
|
33
|
+
|
|
34
|
+
```sh
|
|
35
|
+
# 1. Install uv (one-time)
|
|
36
|
+
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
37
|
+
source ~/.bashrc # macOS default shell is zsh — use ~/.zshrc instead
|
|
38
|
+
|
|
39
|
+
# 2. Install studio-console
|
|
40
|
+
uv tool install https://github.com/selfhosthub/studio-console/releases/download/v1.3.4/studio_console-1.3.4-py3-none-any.whl
|
|
41
|
+
|
|
42
|
+
# 3. Run
|
|
43
|
+
studio-console
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
On first run with no `~/.studio/.env`, the wizard launches. Walk through the sections, save, then go to **Services → Start all**.
|
|
47
|
+
|
|
48
|
+
The wizard creates `~/.studio/` containing `.env` (0600), `docker-compose.yml`, `nginx/studio.conf`, and four data subdirs:
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
~/.studio/
|
|
52
|
+
├── .env, .bootstrapped, docker-compose.yml, nginx/
|
|
53
|
+
├── db/ postgres data (SHS_DB_DATA)
|
|
54
|
+
├── storage/ orgs, uploads, outputs (SHS_STORAGE_ROOT — mounted at /workspace in containers)
|
|
55
|
+
├── models/ model files (SHS_MODELS_ROOT)
|
|
56
|
+
└── backups/ local DB dumps (SHS_BACKUP_ROOT)
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Each data subdir is its own env var, so a cloud deploy can repoint individual roots at CloudSQL, GCS, or a network volume without changing code. **Protect this directory and never delete `.env`** — two of its values cannot be regenerated:
|
|
60
|
+
|
|
61
|
+
- `SHS_CREDENTIAL_ENCRYPTION_KEY` — losing it makes all stored provider API keys unrecoverable.
|
|
62
|
+
- `POSTGRES_PASSWORD` — set on first DB init; the live database keeps using this value, so a regenerated one will lock the API out.
|
|
63
|
+
|
|
64
|
+
Back both up separately (password manager, secrets vault) so you can recover if the host or `.env` is ever lost.
|
|
65
|
+
|
|
66
|
+
### Non-interactive (scripted / CI)
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
SHS_CREDENTIAL_ENCRYPTION_KEY=<32+ char key> \
|
|
70
|
+
SHS_ADMIN_EMAIL=admin@example.com \
|
|
71
|
+
SHS_ADMIN_PASSWORD=<password> \
|
|
72
|
+
studio-console init && studio-console start
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Full list of supported environment variables in [docs/env-vars.md](docs/env-vars.md).
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## Run the Full image
|
|
80
|
+
|
|
81
|
+
The **Full** image (`studio-full`) is a single self-contained container — bundled Postgres, API, UI, and workers under supervisord. No Compose stack, no external database. `launch-full` runs it on your machine and drops you into its in-container console.
|
|
82
|
+
|
|
83
|
+
```sh
|
|
84
|
+
# Launch (workspace defaults to ~/.studio, shared with Split)
|
|
85
|
+
studio-console launch-full --tag 1.0.0
|
|
86
|
+
|
|
87
|
+
# Use a separate workspace to run Full alongside a Split install
|
|
88
|
+
studio-console launch-full --tag 1.0.0 --workspace ~/.studio-full
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
The workspace (mounted at `/workspace`) holds the generated `.env`, the Postgres data dir, and org files — it persists across restarts. You're prompted once for a supervisor username/password; the console remembers them and re-injects on every launch.
|
|
92
|
+
|
|
93
|
+
> **Do not point Full at an existing Split `~/.studio` workspace** unless you mean to share it. Split and Full share the same `.env`/encryption key but **must never run concurrently** against the same data. Use `--workspace` to keep them separate.
|
|
94
|
+
|
|
95
|
+
### Re-entering the console after you exit
|
|
96
|
+
|
|
97
|
+
Exiting the console **does not stop the container** — it keeps running. `launch-full` won't re-attach to an already-running container; instead, exec back in from the host:
|
|
98
|
+
|
|
99
|
+
```sh
|
|
100
|
+
docker exec -it studio-full studio-console # re-open the in-container menu
|
|
101
|
+
|
|
102
|
+
# Or run one-off commands from the host without entering the menu:
|
|
103
|
+
docker exec studio-full studio-console health
|
|
104
|
+
docker exec studio-full studio-console restart api
|
|
105
|
+
docker exec studio-full studio-console logs api
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
Inside the container the console manages services via `supervisorctl` (health, restart, logs, per-service control), plus config, backup, password reset, and Cloudflare setup.
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## Daily Operations
|
|
113
|
+
|
|
114
|
+
```
|
|
115
|
+
Services → Start all bring everything up
|
|
116
|
+
Services → Stop all bring everything down
|
|
117
|
+
Services → Health check API + worker status
|
|
118
|
+
Services → View logs recent logs (all or per-service)
|
|
119
|
+
Services → Stream logs follow live (Ctrl-C to stop)
|
|
120
|
+
Services → Links open UI and API docs in browser
|
|
121
|
+
|
|
122
|
+
Backup → Backup all database + .env + org files
|
|
123
|
+
Backup → Restore DB pick a .sql file from disk
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Backups land in `~/.studio/backups/studio-YYYYMMDD_HHMMSS/`.
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## Upgrading
|
|
131
|
+
|
|
132
|
+
**Studio (the application):**
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
Images → Upgrade
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
Pulls the latest tag from GHCR, updates `SHS_STUDIO_VERSION` in `.env`, and restarts all services. If the new version's major doesn't match your database's major, the upgrade is blocked with a clear message — see [docs/architecture.md](docs/architecture.md#major-version-boundary-detection).
|
|
139
|
+
|
|
140
|
+
**studio-console itself:**
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
uv tool install --force <new-release-url>
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Latest release is always at [github.com/selfhosthub/studio-console/releases/latest](https://github.com/selfhosthub/studio-console/releases/latest).
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## Cutting a release
|
|
151
|
+
|
|
152
|
+
**One command. Never tag, bump `VERSION`, or run `gh release` by hand** — the script does all of it (bumps `VERSION`, updates the README install URL, commits, pushes, tags, builds the wheel, publishes the release with the correct title).
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
# 1. Land your fix on main first (commit + push as normal).
|
|
156
|
+
# 2. Then cut the release — pick the bump size:
|
|
157
|
+
scripts/release-console.sh patch # bug fix 1.0.0 → 1.0.1
|
|
158
|
+
scripts/release-console.sh minor # new feature 1.0.0 → 1.1.0
|
|
159
|
+
scripts/release-console.sh major # breaking 1.0.0 → 2.0.0
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Preview without touching anything: add `--dry-run`. Override the notes with `--message "..."`. Re-cut a release you already published (e.g. it shipped before a fix landed): `scripts/release-console.sh <X.Y.Z> --force`.
|
|
163
|
+
|
|
164
|
+
After release, bump the console pin in the Studio versions file to the new version so the next core/full image build bakes it in.
|
|
165
|
+
|
|
166
|
+
---
|
|
167
|
+
|
|
168
|
+
## CLI Reference
|
|
169
|
+
|
|
170
|
+
```bash
|
|
171
|
+
studio-console # wizard on first run, menu otherwise
|
|
172
|
+
|
|
173
|
+
studio-console start # start all services
|
|
174
|
+
studio-console stop # stop all services
|
|
175
|
+
studio-console restart [service] # restart all or one service
|
|
176
|
+
studio-console health # API + worker health check
|
|
177
|
+
studio-console logs [service] # view recent logs
|
|
178
|
+
studio-console build [image ...] # build images from source
|
|
179
|
+
studio-console upgrade # pull latest version + restart
|
|
180
|
+
studio-console backup # backup database + files
|
|
181
|
+
studio-console restore [path] # restore from backup directory
|
|
182
|
+
studio-console links # print service URLs
|
|
183
|
+
studio-console config # show current .env values
|
|
184
|
+
studio-console config set KEY VALUE # set a single .env value
|
|
185
|
+
studio-console workers # list/scale workers
|
|
186
|
+
studio-console reset-password # reset super admin password
|
|
187
|
+
studio-console wizard # re-run setup wizard
|
|
188
|
+
studio-console init # non-interactive setup from env vars
|
|
189
|
+
studio-console self-update # upgrade studio-console itself
|
|
190
|
+
studio-console version # print version
|
|
191
|
+
|
|
192
|
+
studio-console launch-full [--tag T] [--workspace DIR] # run the Full single-container image on the host
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
For the Full image, run operational subcommands through `docker exec studio-full studio-console <cmd>` — see [Run the Full image](#run-the-full-image).
|
|
196
|
+
|
|
197
|
+
---
|
|
198
|
+
|
|
199
|
+
## Further reading
|
|
200
|
+
|
|
201
|
+
- **[Architecture](docs/architecture.md)** — file layout, state flow, Compose wiring, first-boot, internals (wizard vs init, orphan workers, backup format, major-version detection, deployment contexts).
|
|
202
|
+
- **[Environment variables](docs/env-vars.md)** — every `SHS_*` and supporting var.
|
|
203
|
+
- **[Public hostname topology](docs/topology.md)** — single vs split hostnames, Cloudflare tunnel + Access, IP restrictions.
|
|
204
|
+
- **[VPS + RunPod deployments](docs/vps-runpod.md)** — hybrid setups with GPU worker pods on RunPod.
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## License
|
|
209
|
+
|
|
210
|
+
Studio Console is source-available under the **Studio Console Use License**. It is not open source.
|
|
211
|
+
|
|
212
|
+
You may install, run, and modify Console to manage your own Studio deployments, and to install and manage deployments for individual clients as service work. You may not redistribute, fork, sublicense, or resell it, and you may not use it as the engine of a service that provisions or vends Studio instances to third parties.
|
|
213
|
+
|
|
214
|
+
Console is licensed separately from the Studio platform, which is governed by its own [Studio Use License](https://github.com/selfhosthub/studio/blob/main/LICENSE). Installing Console grants no rights in Studio or in marketplace content.
|
|
215
|
+
|
|
216
|
+
- [LICENSE](LICENSE): the full terms
|
|
217
|
+
- [LEGAL.md](LEGAL.md): operator obligations and third-party responsibilities
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
1.3.4
|