Skip to main content
Version: 0.9.19

Deploy walkthrough

This page walks through a fresh install of AlphaAgent Studio using the guided installer, studioctl. Make sure you have worked through the Prerequisites first. The installer is interactive, idempotent, and resumable — if it is interrupted (you press Ctrl-C, your laptop sleeps, or a transient AWS error occurs), simply re-run studioctl install and it picks up from the first step that has not completed. It remembers your non-secret answers between runs.

Before you start​

  1. Unzip the Studio release bundle you downloaded from the Console.
  2. Open a terminal in the unzipped folder.
  3. Export AWS administrator credentials for your target account and region (environment variables or an AWS profile).
  4. Have your License Token ready.

Running the installer​

From the bundle folder, run:

python3 studioctl.py install

studioctl is a single CLI with a subcommand per lifecycle task. With no command it prints an interactive menu; the commands are:

  • install — fresh deployment (this page)
  • update — move to a new release — see Updating Studio
  • neo4j — configure an external Neo4j connection — see below
  • saml — (re)configure single sign-on — see Single Sign-On (SAML)
  • doctor — verify configuration and health
  • teardown — delete the stacks — see Teardown

Useful flags (global flags go before the command):

python3 studioctl.py --region <region> --profile <aws-profile> install
python3 studioctl.py --dry-run install   # print every action without changing anything
python3 studioctl.py --yes install       # non-interactive (with --config and env vars)

If you have an older runbook that calls python3 deploy.py, it still works for one release: the bundle ships a thin deploy.py that prints a deprecation notice and forwards to studioctl. Switch to studioctl.py directly.

Before any work begins, the installer prints the AWS account, identity, and region it resolved, and asks you to confirm. Always check this matches your intended target.

[Screenshot: studioctl menu and account confirmation]

The License Token and Neo4j password are entered without echoing to the screen and are never written to disk. Other answers (stack names, domain, certificate, Cognito prefix, Neo4j mode) are saved locally so re-runs and updates pre-fill themselves. At any prompt you can type ? for contextual help.

The steps of a fresh install​

1. Preflight​

The installer runs a read-only environment check: your identity, that the Console is reachable, that there are no conflicting pre-existing AlphaAgent resources, that Bedrock model access and token quotas are sufficient, that your ACM certificate is ISSUED and covers your domain, and that your chosen Cognito prefix is available. If anything fails, it asks whether to continue (defaulting to no). Fix blockers before proceeding.

2. Foundation stack​

Creates the networking, data stores, container registry, Cognito user pool, and secret placeholders in your account. Your License Token is stored here as a one-time bootstrap secret so Studio can activate itself on first boot. If you chose self-hosted Neo4j, this stack also provisions the encrypted, multi-AZ storage (EFS) that the Neo4j service will use.

3. Neo4j credentials​

Early in the install you chose how to provide Neo4j (see Prerequisites). There is no manual pause in either mode:

  • Self-hosted (managed by Studio): the installer generates a strong random password, stores it securely, and points Studio at the in-VPC Neo4j service it will run for you (bolt://neo4j:7687). Zero-touch — nothing for you to launch or paste.
  • External (bring your own): a placeholder is seeded now and the install finishes normally. Once your own Neo4j is reachable from the deployment's network, you run a single command to connect it (see Finishing up).

4. Push the Studio image​

The installer loads the Studio application image from the bundle and pushes it to your ECR registry. This is the image your Fargate services will run.

5. Seed configuration secrets​

Populates Studio's configuration secrets in AWS Secrets Manager from the foundation stack's outputs and your Neo4j settings. This step also resolves the Bedrock model identifiers for your residency zone. Re-running is safe — existing security keys are preserved, never regenerated.

6. Upload the Studio web app​

Syncs the prebuilt Studio web application to its S3 bucket so it can be served through the load balancer.

7. Load balancer, compute, and services stacks​

Creates the internet-facing load balancer (with its SSO-enforcing listener), the Fargate cluster and roles, and the Studio service definitions — each stack building on the previous one. If you chose self-hosted Neo4j, the Neo4j service is created here too. When this completes, the Studio services start up on Fargate.

8. Configure single sign-on (required)​

Sign-in is SSO-only, so SAML setup is part of every fresh install. The installer prints the service-provider values you must register in your identity provider, then takes your IdP metadata and wires up the Cognito user pool and the load balancer's listener to require SSO. Full details, including the exact values and attribute mappings, are in Single Sign-On (SAML).

9. Verify configuration​

The installer runs a final read-only check (the same one available any time as studioctl doctor) that confirms each service resolved its configuration. For external Neo4j it will note that Neo4j is not yet configured — expected until you run studioctl neo4j.

Finishing up​

The installer prints a DNS instruction: create a CNAME/ALIAS record pointing your domain at the load balancer's address. Create that record with your DNS provider.

Then browse to your domain, complete SSO sign-in, and you are in Studio. Within a few minutes the running Studio activates and begins sending heartbeats, and the Console license page for your key turns healthy and starts reflecting usage.

If you chose external Neo4j, the installer ends with the exact command to connect your own Neo4j once it is reachable from the deployment's network (inbound on port 7687 from the Studio services). Knowledge-base features stay unavailable until you run it:

python3 studioctl.py neo4j --uri bolt://<host>:7687 --user neo4j --password <secret>

This validates the connection, writes the credentials, and rolls the knowledge-base services so they pick them up. See Knowledge graphs in depth.

[Screenshot: Studio sign-in via SSO after deploy]

If something goes wrong​

The installer streams progress and stops on errors. Common issues (preflight failures, certificate problems, Cognito prefix collisions, Neo4j connectivity) are covered in Troubleshooting. Because the installer is resumable and idempotent, you can fix the underlying problem and re-run studioctl install; completed steps are skipped and it continues from where it stopped. You can also re-run a specific step with studioctl install --restart-from <step>.