# Roadrunner SMB — Quick Start Guide

**Time to first share**: approximately 20–30 minutes after stack deployment completes.

---

## Prerequisites

Before deploying, confirm you have:

- [ ] An AWS account with sufficient service quotas: EC2, EFS, DynamoDB, ECS, NLB
- [ ] A VPC with private subnets across at least 2 Availability Zones
- [ ] NAT Gateway (or VPC endpoints) providing outbound internet access from private subnets
- [ ] An Active Directory domain reachable from the VPC (on-premises via Direct Connect/VPN, or AWS Managed Microsoft AD)
- [ ] DNS resolution for the AD domain from the VPC (DHCP options or Route 53 Resolver rules)
- [ ] A domain account with permission to join computers to the domain (you will enter these credentials in the setup wizard — no pre-created secret is required)
- [ ] IAM permissions to deploy CloudFormation stacks

---

## Step 1 — Deploy the Marketplace Stack

1. Subscribe to **Roadrunner SMB** in the [AWS Marketplace](https://aws.amazon.com/marketplace/)
2. Click **Continue to Subscribe**, then **Continue to Configuration**
3. Select your region, then click **Continue to Launch**
4. Choose **Launch CloudFormation** and click **Launch**
5. Fill in the CloudFormation parameters:

   | Parameter | What to enter |
   |---|---|
   | `VpcId` | Your VPC ID |
   | `PrivateSubnetIds` | At least 2 private subnet IDs across different AZs (comma-separated) |
   | `AdDomainFqdn` | Your AD domain FQDN (e.g. `corp.example.com`) |
   | `DcDnsIp1` | Primary domain controller IP |
   | `DcDnsIp2` | Secondary domain controller IP (optional) |
   | `AdminCidr` | CIDR of machines that will access the Admin UI (e.g. `10.0.0.0/8`) |
   | `BackendImageUri` | *(pre-filled from Marketplace)* |

6. Click **Next**, accept capabilities, then **Create stack**
7. Wait for the stack to reach `CREATE_COMPLETE` (typically 5–10 minutes)

---

## Step 2 — Find the Admin UI URL

1. In the CloudFormation console, click your stack → **Outputs** tab
2. Copy the value of `AdminUIUrl` — this is your Admin UI address
3. Open the URL in a browser **from a machine within the `AdminCidr` range**
4. The First-Time Setup wizard will load automatically

> **If the page doesn't load**: verify your browser machine's IP is within `AdminCidr` and that you're connecting from within the VPC (e.g. via VPN or a bastion host).

---

## Step 3 — Retrieve the Bootstrap Secret

The First-Time Setup wizard requires a one-time **Bootstrap Secret** to authenticate the initial configuration. The secret is pre-generated by the CloudFormation stack and stored in AWS Secrets Manager.

**To find it:**

1. In the CloudFormation console, click your stack → **Outputs** tab
2. Click the link next to **`BootstrapSecretConsoleUrl`** — this opens the secret directly in the Secrets Manager console
3. Click **"Retrieve secret value"**
4. Copy the secret value

> **Alternative**: search for the secret ARN shown in the **`BootstrapSecretArn`** output directly in the Secrets Manager console.

> The bootstrap secret is valid only until First-Time Setup is completed. It is automatically disabled once setup is complete and cannot be reused.

---

## Step 4 — Complete First-Time Setup

The First-Time Setup (FTS) wizard runs only once and walks through 5 steps:

### 4a — Enter Bootstrap Secret
Paste the secret retrieved from Secrets Manager (Step 3) and click **Continue**.

### 4b — Establish HTTPS
Click **Generate TLS Certificate**. The appliance generates a self-signed certificate and redirects you to HTTPS. Accept the certificate warning in your browser — this is expected for the self-signed cert.

### 4c — Join Active Directory
Enter your domain join credentials directly in the wizard:

| Field | What to enter |
|---|---|
| Domain | Your AD domain FQDN (e.g. `corp.example.com`) |
| Join Username | A domain account with computer-join permission (e.g. `svc-rrsmb-join`) |
| Join Password | Password for that account |
| Domain Controller IP | *(optional)* Only if DNS forwarding to AD is not configured |

Click **Test** to run an AD preflight check, then click **Join Domain**. Join takes 30–90 seconds.

### 4d — Set Appliance Owner Password
Set the password for the local break-glass administrator account (`rrsmb-admin`). Store this securely — it is used if AD authentication is unavailable.

Minimum 12 characters required.

### 4e — Claim Appliance Admin
Log in with your personal **domain account** to claim Appliance Admin rights. This grants your AD account full access to the Admin UI going forward.

Click **Claim Admin** and confirm if prompted.

### 4f — Complete Setup
Click **Complete First-Time Setup**. The bootstrap secret is permanently disabled. You are redirected to the Admin UI login page.

---

## Step 5 — Log In to the Admin UI

1. Log in with the domain account you used to claim admin (Step 4e)
2. You will land on the **Dashboard** showing cluster health and pipeline metrics

---

## Step 6 — Create Your First Share

1. Click **Shares** in the left navigation
2. Click **Create Share**
3. Enter a share name (e.g. `data`)
4. Configure permissions (choose a preset or customize AD groups)
5. Click **Create**
6. Wait 15–60 seconds for the share to materialize across the cluster

---

## Step 7 — Mount the Share from Windows

1. Open **File Explorer** on a domain-joined Windows machine
2. In the address bar, type:
   ```
   \\<NlbDnsName>\<sharename>
   ```
   Use the `NlbDnsName` value from CloudFormation Outputs, for example:
   ```
   \\rrsmb-nlb-abc123.elb.us-east-1.amazonaws.com\data
   ```
3. Press Enter and authenticate with your Active Directory credentials

---

## Step 8 — Verify

- [ ] Share appears in File Explorer
- [ ] You can create a folder and file in the share
- [ ] Another domain user with appropriate permissions can access the share

---

## Common First-Time Issues

| Symptom | Likely cause | Fix |
|---|---|---|
| Admin UI unreachable | Browser machine outside `AdminCidr` | Check security group inbound rule; connect from within VPC |
| Bootstrap secret not found | Wrong log group or stream | Search all streams for `=== BOOTSTRAP SECRET ===` |
| Domain join fails — DNS error | DNS not resolving AD domain | Enable Manual DC IP in the wizard and enter the DC IP directly |
| Domain join fails — credentials | Wrong username/password or account locked | Verify account in AD; try `DOMAIN\username` format |
| Share mount fails | NLB not yet healthy | Wait 2 minutes after share creation; check Cluster page in Admin UI |
| "Access denied" on mount | User not in share ACL | Add user/group in the share's Permissions tab |
| "Cannot find network path" | Wrong server name | Use the `NlbDnsName` CFN output, not the Admin UI URL |

See the [Support & Troubleshooting](support-troubleshooting.md) guide for more.

---

## Next Steps

- Read the [Admin Guide](admin-guide.md) for share management, cluster health, and logs
- Review [Known Limitations](known-limitations.md) before deploying for production use
- Contact [support](support-troubleshooting.md#how-to-get-help) if you need assistance