Skip to content

quickstart.mdx

Latest commit

 

History

History
438 lines (338 loc) · 12.5 KB

quickstart.mdx

File metadata and controls

438 lines (338 loc) · 12.5 KB
title Quickstart
description Create and manage your first supported LibOps site

Get started in four steps

Create your first supported LibOps site and start managing it through the dashboard, Slack, sitectl, and the platform API.

Site managers can do most of this work in the dashboard. Engineers can use the CLI examples when they need automation, repository access, or local development workflows.

Step 1: Create your account

You can create an account using either the CLI or web browser. 
**Option A: Using sitectl CLI**

Install sitectl and authenticate:

```bash
# Download sitectl (see CLI documentation for your platform)
curl -L https://github.com/libops/sitectl/releases/latest/download/sitectl_linux_amd64 -o sitectl
chmod +x sitectl
sudo mv sitectl /usr/local/bin/

# Login or register
sitectl libops login
```

This will open your browser where you can:
- Sign in with Google
- Or create an account with email/password

**Option B: Using your browser**

Visit the [LibOps dashboard](https://dash.libops.io) to:
- Sign in with Google
- Or register with email/password

<Tip>After logging in via browser, run `sitectl libops login` to authenticate your CLI.</Tip>
Confirm you're logged in: 
```bash
sitectl whoami
```

You should see your authentication status and token information.

Step 2: Create your infrastructure

For site managers, the dashboard path is the recommended path:

  1. Open the LibOps dashboard.
  2. Create or choose your organization.
  3. Create a project for the collection, journal, repository, or web property.
  4. Create a site from a supported LibOps template.
  5. Keep the site private while staff review it, then follow the publishing checklist when it is ready.

Engineers can use the same resource model through sitectl:

Organizations are the top-level container for all your resources. 
```bash
sitectl libops create organization \
  --name "Example Museum" \
  --location LOCATION_US \
  --region us-central1
```

Save the organization ID from the output, or retrieve it later:

```bash
# List all organizations
sitectl libops list organizations

# Get organization ID as JSON
ORG_ID=$(sitectl libops list organizations --format json | jq -r '.[0].ID')
echo $ORG_ID
```
Projects group related sites together within an organization. 
```bash
# Replace with your organization ID
sitectl libops create project \
  --organization-id org_abc123 \
  --name "Digital Collections" \
  --region us-central1 \
  --zone us-central1-f \
  --machine-type e2-standard-2 \
  --disk-size-gb 20
```

Or capture the project ID automatically:

```bash
PROJECT_ID=$(sitectl libops create project \
  --organization-id $ORG_ID \
  --name "Digital Collections" \
  --region us-central1 \
  --zone us-central1-f \
  --machine-type e2-standard-2 \
  --disk-size-gb 20 \
  --format json | jq -r '.id')

echo "Created project: $PROJECT_ID"
```
Sites represent individual Docker Compose deployments. 
```bash
# Replace with your project ID
sitectl libops create site \
  --project-id proj_xyz789 \
  --name "collections" \
  --github-repository git@github.com:example/collections.git \
  --github-ref heads/main \
  --compose-path /mnt/disks/data/compose \
  --compose-file docker-compose.yml \
  --application-type islandora
```

Or capture the site ID:

```bash
SITE_ID=$(sitectl libops create site \
  --project-id $PROJECT_ID \
  --name "collections" \
  --github-repository git@github.com:example/collections.git \
  --github-ref heads/main \
  --compose-path /mnt/disks/data/compose \
  --compose-file docker-compose.yml \
  --application-type islandora \
  --format json | jq -r '.id')

echo "Created site: $SITE_ID"
```

<Tip>Keep your site ID handy - you'll need it for adding secrets and configuring access.</Tip>

Step 3: Configure your site

Store your application's sensitive configuration as encrypted secrets. 
```bash
# Database credentials
sitectl libops create secret \
  --site-id site_123abc \
  --name "DATABASE_URL" \
  --value "mysql://user:password@mariadb.example.com/myapp"

# API keys
sitectl libops create secret \
  --site-id site_123abc \
  --name "STRIPE_SECRET_KEY" \
  --value "sk_live_abc123xyz"

# Application secrets
sitectl libops create secret \
  --site-id site_123abc \
  --name "APP_SECRET" \
  --value "your-secret-key-here"
```

<Note>Secret values are encrypted and never displayed after creation.</Note>
LibOps sites are IP-allowlisted by default. Add rules for the people who should reach the site, or add a public rule when a production site is ready to publish. 
```bash
# Allow office network
sitectl libops create firewall \
  --site-id site_123abc \
  --cidr "203.0.113.0/24" \
  --name "office" \
  --type FIREWALL_RULE_TYPE_HTTPS_ALLOWED

# Allow specific admin IP
sitectl libops create firewall \
  --site-id site_123abc \
  --cidr "192.0.2.100/32" \
  --name "admin-workstation" \
  --type FIREWALL_RULE_TYPE_HTTPS_ALLOWED
```

<Note>For public production launches, follow [Getting a Site Ready to Publish](/platform/getting-site-ready-to-publish) and add a `0.0.0.0/0` firewall rule to the production site when it should accept traffic from any IPv4 address.</Note>
Invite team members to collaborate on your site. 
```bash
# Add an admin
sitectl libops create member \
  --site-id site_123abc \
  --email "admin@example.com" \
  --role "owner"

# Add a developer
sitectl libops create member \
  --site-id site_123abc \
  --email "developer@example.com" \
  --role "developer"
```

Step 4: Deploy your application

Set up a remote context to connect to your deployment server. 
```bash
sitectl config set-context production \
  --type remote \
  --hostname collections-host.example.edu \
  --ssh-user deploy \
  --ssh-port 22 \
  --ssh-key ~/.ssh/id_rsa \
  --project-dir /var/www/app \
  --profile production \
  --default
```

<Tip>Make sure your SSH key has access to the remote server.</Tip>
Deploy your application using Docker Compose commands through sitectl. 
```bash
# Pull latest images
sitectl compose pull --context production

# Start services
sitectl compose up --context production

# Check status
sitectl compose ps --context production

# View logs
sitectl compose logs -f --context production
```

sitectl automatically:
- Connects to your remote server via SSH
- Applies the correct Docker Compose profile
- Injects environment files
- Runs commands in the correct directory
Alternatively, configure a local context for development work. 
```bash
sitectl config set-context local \
  --type local \
  --project-dir ~/my-app \
  --profile development \
  --env-file .env.local \
  --default

# Start local services
sitectl compose up

# View logs
sitectl compose logs -f

# Run commands in containers
sitectl compose exec app bash
```

Complete example workflow

Here's a complete example that creates everything from scratch:

# 1. Login
sitectl libops login

# 2. Create organization
ORG_ID=$(sitectl libops create organization \
  --name "Example Museum" \
  --location LOCATION_US \
  --region us-central1 \
  --format json | jq -r '.id')

echo "Organization ID: $ORG_ID"

# 3. Create project
PROJECT_ID=$(sitectl libops create project \
  --organization-id $ORG_ID \
  --name "Digital Collections" \
  --region us-central1 \
  --zone us-central1-f \
  --machine-type e2-standard-2 \
  --disk-size-gb 20 \
  --format json | jq -r '.id')

echo "Project ID: $PROJECT_ID"

# 4. Create site
SITE_ID=$(sitectl libops create site \
  --project-id $PROJECT_ID \
  --name "collections" \
  --github-repository git@github.com:example/collections.git \
  --github-ref heads/main \
  --compose-path /mnt/disks/data/compose \
  --compose-file docker-compose.yml \
  --application-type islandora \
  --format json | jq -r '.id')

echo "Site ID: $SITE_ID"

# 5. Add secrets
sitectl libops create secret --site-id $SITE_ID --name "DATABASE_URL" --value "mysql://..."
sitectl libops create secret --site-id $SITE_ID --name "REDIS_URL" --value "redis://..."
sitectl libops create secret --site-id $SITE_ID --name "API_KEY" --value "sk_live_..."

# 6. Add firewall rules
sitectl libops create firewall --site-id $SITE_ID --cidr "203.0.113.0/24" --name "office" --type FIREWALL_RULE_TYPE_HTTPS_ALLOWED
sitectl libops create firewall --site-id $SITE_ID --cidr "192.0.2.0/24" --name "vpn" --type FIREWALL_RULE_TYPE_HTTPS_ALLOWED
# Add this only when the production site is ready for public IPv4 traffic
sitectl libops create firewall --site-id $SITE_ID --cidr "0.0.0.0/0" --name "public-production-web" --type FIREWALL_RULE_TYPE_HTTPS_ALLOWED

# 7. Add team members
sitectl libops create member --site-id $SITE_ID --email "admin@acme.com" --role "owner"
sitectl libops create member --site-id $SITE_ID --email "dev@acme.com" --role "developer"

# 8. Configure remote context
sitectl config set-context production \
  --type remote \
  --hostname collections-host.example.edu \
  --ssh-user deploy \
  --ssh-key ~/.ssh/id_rsa \
  --project-dir /var/www/collections \
  --profile production

# 9. Deploy
sitectl compose pull --context production
sitectl compose up --context production

# 10. Check status
sitectl compose ps --context production

Next steps

Now that you have your first site deployed, explore these key features:

Learn how to switch between local and remote environments Master hierarchical secrets and environment variables Access remote services locally for debugging Explore all Docker Compose integration features Automate your infrastructure with the REST API Add team members and configure role-based access

Common tasks

Access a remote database

# Forward MariaDB to a local port
sitectl port-forward 3306:mariadb:3306 --context production

# Connect with local tools
mysql -h 127.0.0.1 -P 3306 -u myuser -p mydb

Update secrets

# List current secrets
sitectl libops list secrets --site-id $SITE_ID

# Update a secret value
SECRET_ID=$(sitectl libops list secrets --site-id $SITE_ID --format json | \
  jq -r '.[] | select(.Key == "API_KEY") | .ID')

sitectl libops edit secret $SECRET_ID --site-id $SITE_ID --value "new_secret_value"

Check deployment logs

# Follow all logs
sitectl compose logs -f --context production

# Filter by service
sitectl compose logs -f nginx --context production

# Show last 100 lines
sitectl compose logs --tail=100 --context production
**Need help?** Visit our [CLI documentation](/cli/introduction) or [contact support](mailto:info@libops.io).