Skip to content

quickstart.mdx

Latest commit

 

History

History
400 lines (305 loc) · 10.3 KB

quickstart.mdx

File metadata and controls

400 lines (305 loc) · 10.3 KB
title Quickstart
description Deploy your first Docker Compose application with LibOps

Get started in four steps

Deploy your first site on LibOps and start managing your Docker Compose applications in the cloud.

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 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 [https://api.libops.io/login](https://api.libops.io/login) to:
- Sign in with Google
- Or register with email/password

<Tip>After logging in via browser, run `sitectl 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

Organizations are the top-level container for all your resources. 
```bash
sitectl create organization \
  --name "My Company" \
  --description "Production infrastructure"
```

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

```bash
# List all organizations
sitectl list organizations

# Get organization ID as JSON
ORG_ID=$(sitectl 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 create project \
  --organization-id org_abc123 \
  --name "Production Apps" \
  --description "Customer-facing applications"
```

Or capture the project ID automatically:

```bash
PROJECT_ID=$(sitectl create project \
  --organization-id $ORG_ID \
  --name "Production Apps" \
  --description "Customer-facing applications" \
  --format json | jq -r '.id')

echo "Created project: $PROJECT_ID"
```
Sites represent individual Docker Compose deployments. 
```bash
# Replace with your project ID
sitectl create site \
  --project-id proj_xyz789 \
  --name "web-app" \
  --domain "app.example.com" \
  --description "Main web application"
```

Or capture the site ID:

```bash
SITE_ID=$(sitectl create site \
  --project-id $PROJECT_ID \
  --name "web-app" \
  --domain "app.example.com" \
  --description "Main web application" \
  --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 create secrets \
  --site-id site_123abc \
  --key "DATABASE_URL" \
  --value "postgresql://user:password@db.example.com/myapp"

# API keys
sitectl create secrets \
  --site-id site_123abc \
  --key "STRIPE_SECRET_KEY" \
  --value "sk_live_abc123xyz"

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

<Note>Secret values are encrypted and never displayed after creation.</Note>
Control who can access your site with IP-based firewall rules. 
```bash
# Allow office network
sitectl create firewall \
  --site-id site_123abc \
  --cidr "203.0.113.0/24" \
  --description "Office network"

# Allow specific admin IP
sitectl create firewall \
  --site-id site_123abc \
  --cidr "192.0.2.100/32" \
  --description "Admin workstation"
```
Invite team members to collaborate on your site. 
```bash
# Add an admin
sitectl create members \
  --site-id site_123abc \
  --email "admin@example.com" \
  --role "admin"

# Add a developer
sitectl create members \
  --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 prod.example.com \
  --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 login

# 2. Create organization
ORG_ID=$(sitectl create organization \
  --name "ACME Corporation" \
  --description "Main production infrastructure" \
  --format json | jq -r '.id')

echo "Organization ID: $ORG_ID"

# 3. Create project
PROJECT_ID=$(sitectl create project \
  --organization-id $ORG_ID \
  --name "E-commerce Platform" \
  --description "Online store and APIs" \
  --format json | jq -r '.id')

echo "Project ID: $PROJECT_ID"

# 4. Create site
SITE_ID=$(sitectl create site \
  --project-id $PROJECT_ID \
  --name "production-web" \
  --domain "shop.acme.com" \
  --description "Production storefront" \
  --format json | jq -r '.id')

echo "Site ID: $SITE_ID"

# 5. Add secrets
sitectl create secrets --site-id $SITE_ID --key "DATABASE_URL" --value "postgresql://..."
sitectl create secrets --site-id $SITE_ID --key "REDIS_URL" --value "redis://..."
sitectl create secrets --site-id $SITE_ID --key "API_KEY" --value "sk_live_..."

# 6. Add firewall rules
sitectl create firewall --site-id $SITE_ID --cidr "203.0.113.0/24" --description "Office"
sitectl create firewall --site-id $SITE_ID --cidr "192.0.2.0/24" --description "VPN"

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

# 8. Configure remote context
sitectl config set-context production \
  --type remote \
  --hostname prod.acme.com \
  --ssh-user deploy \
  --ssh-key ~/.ssh/id_rsa \
  --project-dir /var/www/shop \
  --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 PostgreSQL to local port
sitectl port-forward 5432:postgres:5432 --context production

# Connect with local tools
psql -h localhost -p 5432 -U myuser mydb

Update secrets

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

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

sitectl edit secret $SECRET_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).