diff --git a/docs/.vale/styles/config/vocabularies/Suga/accept.txt b/docs/.vale/styles/config/vocabularies/Suga/accept.txt index 14480b7f..4673fe43 100644 --- a/docs/.vale/styles/config/vocabularies/Suga/accept.txt +++ b/docs/.vale/styles/config/vocabularies/Suga/accept.txt @@ -284,4 +284,25 @@ nav prev next toc -uv \ No newline at end of file +uv +Monorepo +monorepo +Minio +Prisma +SQLAlchemy +datasource +sqlalchemy +ORMs +api +debugpy +dlv +pgx +sqlx +pgxpool +playsInline +Reusability +Pulumi +SREs +DevOps +cicd +enablement \ No newline at end of file diff --git a/docs/cli/login.mdx b/docs/cli/login.mdx index bc539efe..2af5a5c8 100644 --- a/docs/cli/login.mdx +++ b/docs/cli/login.mdx @@ -9,7 +9,7 @@ Login to the Suga CLI. suga login ``` -Opens your browser to complete the authentication flow with the Suga platform. This is required for all CLI operations during the early access period. +Opens your browser to complete the authentication flow with the Suga platform. This is required for most CLI operations. ## What happens during login diff --git a/docs/core/infrastructure-generation.mdx b/docs/core/infrastructure-generation.mdx new file mode 100644 index 00000000..d2eedc88 --- /dev/null +++ b/docs/core/infrastructure-generation.mdx @@ -0,0 +1,200 @@ +--- +title: "Infrastructure Generation" +description: "How Suga transforms projects into production-ready Terraform" +--- + +When you run `suga build`, Suga transforms your high-level project specification into production-ready Terraform code. This page explains how this transformation works, what gets generated, and how to customize the output. + +## The Build Process + +The `suga build` command orchestrates a multi-step process: + + + + Suga reads your `suga.yaml` file and validates the configuration: + + ```yaml title="suga.yaml" + target: suga/aws@1 + name: my-app + + services: + api: + subtype: lambda + dev: + script: npm run dev + + buckets: + subtype: s3 + uploads: + access: + api: [read, write] + ``` + + + + Suga retrieves the target platform specification from the registry: + + ```bash + # Platform: suga/aws@1 + - Services: lambda, fargate + - Buckets: s3 + - Databases: neon + - Entrypoints: cloudfront + - Infrastructure: vpc, loadbalancer, security-groups + ``` + + + + Each project resource is mapped to a platform blueprint, by the selected subtype: + + ```yaml suga.yaml + services: + api: + subtype: fargate + + buckets: + uploads: + subtype: s3 + ``` + + ``` + Project Platform Blueprint Plugin + ------- ------------------ ------ + service "api" → services.fargate → suga/aws/fargate + bucket "uploads" → buckets.s3 → suga/aws/s3-bucket + ``` + + + + + Suga then uses Terraform CDK to resolve the modules, variables and other configuration to produce a Terraform stack. + + ``` + terraform/stacks/my-app/ + ├── cdk.tf.json # Main Terraform Entrypoint + └── .terraform/ # Plugin Terraform modules + └── modules/ + ├── api/ + ├── api_image/ + ├── uploads_bucket/ + └── ... + ``` + + + +## Module Naming + +Suga generates consistent module names for application resources: + +### Terraform Module Names + +Pattern: `{resource_name}_{submodule_name}` + +```hcl +module "api" # Service named "api" +module "api_image" # Container image submodule for the "api" service +module "uploads" # Bucket named "uploads" +``` + +## Dependency Management + +Suga automatically manages resource dependencies: + +### Explicit Dependencies + +Defined by platform: + +```yaml title="Platform blueprint" +services: + fargate: + depends_on: + - ${infra.aws_vpc} + - ${infra.aws_lb} +``` + +Results in: + +```hcl title="Generated Terraform" +module "service_api" { + # ... + depends_on = [ + module.aws_vpc, + module.aws_lb + ] +} +``` + +### Implicit Dependencies + +Created by resource references: + +```hcl title="Automatic dependency" +module "service_api" { + vpc_id = module.aws_vpc.vpc_id # Creates implicit dependency +} +``` + +## Multi-Environment Support + +The same generated Terraform can deploy to multiple environments using Terraform workspaces and environment-specific variable files. This allows you to maintain a single infrastructure definition while customizing configuration for dev, staging, and production. + + + Learn how to manage multiple environments with Terraform workspaces and variables + + +See the [CLI reference](/cli/build) for complete build options. + +## Getting Help + +If you encounter issues during build: + +1. Review platform documentation in the [platform browser](https://app.addsuga.com/browse/platforms) +2. Contact [Suga support](/support) + +## Best Practices + +### 1. Version Control Generated Terraform + +Commit generated Terraform to version control: + +```bash +git add terraform/ +git commit -m "Update infrastructure" +``` + +Benefits: +- Track infrastructure changes over time +- Review Terraform diffs in pull requests +- Rollback if needed + +### 2. Validate Before Deploying + +Always validate and preview: + +```bash +suga build +cd terraform/stacks/my-app +terraform init +terraform validate +terraform plan # Review before apply +``` + +## Learn More + + + + Understand the deployment process + + + + Complete CLI reference for `suga build` + + + + Learn how platforms define infrastructure + + + + Best practices for Terraform configuration + + diff --git a/docs/core/local-development.mdx b/docs/core/local-development.mdx new file mode 100644 index 00000000..fc43dbc6 --- /dev/null +++ b/docs/core/local-development.mdx @@ -0,0 +1,355 @@ +--- +title: "Local Development" +description: "Develop and test cloud applications entirely on your local machine" +--- + +Suga's local development environment (`suga dev`) lets you build and test cloud applications entirely on your local machine without cloud access, accounts, or costs. This page explains how local development works, what's emulated, and best practices for productive local workflows. + +## The Development Server + +The `suga dev` command starts a local development server that: + +- **Emulates cloud resources** - Buckets, entrypoints, databases, schedules +- **Runs your services** - Using the `dev.script` from your `suga.yaml` +- **Hot reloads code** - Automatically restarts services when files change +- **Provides local URLs** - Access your application at `localhost` ports + +```bash title="Start local development" +suga dev +``` + +```bash title="Example output" +⚡ Suga v0.0.1 + - App: my-app + - Addr: :50051 + +Services + +✓ Starting [api] + +Entrypoints + +✓ Starting [web] http://localhost:3000 + +Use Ctrl-C to exit +``` + +## What Gets Emulated + +### Services + +Your application services run locally using their `dev.script`: + +```yaml title="suga.yaml" +services: + api: + dev: + script: npm run dev + worker: + dev: + script: python main.py +``` + +Each service: +- Runs as a separate process +- Gets automatically restarted on code changes +- Receives environment variables from `suga.yaml` +- Can communicate with emulated resources + +### Buckets (Object Storage) + +Buckets are emulated using the local filesystem: + +``` +project-root/ +└── .suga/ + └── buckets/ + └── uploads/ # Bucket named "uploads" + ├── file1.txt + └── file2.jpg +``` + +**Features:** +- Read/write/delete operations work like cloud storage +- Files persist between `suga dev` sessions +- Pre-seed buckets by placing files in `.suga/buckets/{bucket-name}/` +- View files directly in the file explorer + +**SDK Operations:** + +Use the generated Suga client to interact with buckets: + +```typescript title="Works locally and in production" +// Write file +await suga.uploads.write('file.txt', Buffer.from('Hello!')); + +// Read file +const data = await suga.uploads.read('file.txt'); + +// Delete file +await suga.uploads.delete('file.txt'); +``` + +Local behavior: +- `write()` creates files in `.suga/buckets/uploads/` +- `read()` reads from `.suga/buckets/uploads/` +- `delete()` removes files from `.suga/buckets/uploads/` + + + Learn about generated client libraries for cloud-agnostic resource access + + +### Entrypoints (HTTP Routing) + +Entrypoints provide local HTTP servers with routing: + +```yaml title="suga.yaml" +services: + api: ... +buckets: + frontend: ... +entrypoints: + web: + routes: + /api/: + name: api + /: + name: frontend +``` + +Running `suga dev` will result in: + +``` +http://localhost:3000/api/ → Routes to 'api' service +http://localhost:3000/ → Routes to 'frontend' service +``` + +**Features:** +- Path-based routing like production CDN +- Request/response logging +- CORS handling + +### Databases + +PostgreSQL databases are automatically run locally: + +```yaml title="suga.yaml" +databases: + main: + access: + api: [query] + env_var_key: DATABASE_URL +``` + +**Features:** +- Automatic PostgreSQL instance created per database +- Connection strings injected into services via environment variables +- Data persists between `suga dev` sessions +- Full PostgreSQL compatibility for development + +**How it works:** + +During `suga dev`, Suga: +1. Starts a local PostgreSQL instance for each database using Docker +2. Injects connection strings into services with access +3. Makes databases available on local ports + +Services receive the connection string exactly as they would in production: + +```typescript title="Works locally and in production" +import { Pool } from 'pg'; + +const pool = new Pool({ + connectionString: process.env.DATABASE_URL +}); + +await pool.query('CREATE TABLE IF NOT EXISTS users (id SERIAL PRIMARY KEY, name TEXT)'); +await pool.query('INSERT INTO users (name) VALUES ($1)', ['Alice']); +const result = await pool.query('SELECT * FROM users'); +console.log(result.rows); +``` + +## The `.suga` Directory + +Suga creates a `.suga` directory in your project for local state: + +``` +.suga/ +├── buckets/ # Bucket contents +│ └── uploads/ +├── logs/ # Service logs +│ ├── api.log +│ └── worker.log +└── dev.json # Development server state +``` + + + Add `.suga/` to your `.gitignore` - this directory contains local development state and should not be committed. + + +## Development Workflow + +### Starting Development + +```bash +# Start all services and resources +suga dev +``` + +### Making Code Changes + +1. **Edit your service code** - Changes are detected automatically +2. **Service restarts** - Using a watcher in your dev script +3. **Test immediately** - New code is running + +### Debugging Services + +Standard debugging tools work normally: + + + + ```json title="package.json" + { + "scripts": { + "dev": "node --inspect src/index.js" + } + } + ``` + + Then connect Chrome DevTools or VS Code debugger to `localhost:9229`. + + + + ```yaml title="suga.yaml" + services: + api: + dev: + script: python -m debugpy --listen 5678 main.py + ``` + + Then connect VS Code or PyCharm debugger to `localhost:5678`. + + + + ```bash title="Use delve debugger" + dlv debug --headless --listen=:2345 --api-version=2 + ``` + + Then connect GoLand or VS Code debugger to `localhost:2345`. + + + +### Viewing Logs + +Service logs are written to `.suga/logs/`: + +```bash +# Tail service logs +tail -f .suga/logs/api.log + +# Or use your preferred log viewer +cat .suga/logs/api.log | grep ERROR +``` + +### Seeding Local Data + +Pre-populate buckets for testing: + +```bash +# Create test files +mkdir -p .suga/buckets/uploads +echo "Test content" > .suga/buckets/uploads/test.txt + +# Start dev server - files are available immediately +suga dev +``` + +```typescript title="Read pre-seeded data" +const data = await suga.uploads.read('test.txt'); +console.log(data); // "Test content" +``` + +## Environment Variables + +Services receive environment variables defined in `suga.yaml`: + +```yaml title="suga.yaml" +services: + api: + env: + EXTERNAL_API_KEY: dev-key-12345 + DEBUG: "true" + dev: + script: npm run dev + +databases: + main: + access: + api: [query] + env_var_key: DATABASE_URL # Automatically injected during dev and production +``` + +During `suga dev`: +- Service receives environment variables from `env` config +- Database connection strings automatically injected based on `env_var_key` +- Same variables are available in production (after Terraform deployment) +- Use for configuration, feature flags, etc. + + + Use different values for local vs production by adding platform-specific overrides or using Terraform variables. + + +## Service Communication + + + Direct service-to-service communication is coming soon. For now, services can communicate through shared databases, buckets or entrypoint URLs. + + +## Limitations + +Local emulation provides high fidelity but has some limitations: + +### Not Emulated + +- **Cloud-specific features** - Lambda layers, CloudFront behaviors, CDN caching +- **Scaling** - Auto-scaling, load balancing across multiple instances +- **Managed services** - Cloud-specific features like S3 lifecycle policies +- **Networking** - VPCs, security groups, actual cloud networking + +### Performance Differences + +- **Cold starts** - Service cold starts don't occur locally +- **Latency** - No network latency between services +- **Resource limits** - Local resources not limited like a deployed service (memory, timeout) + +### Workarounds + +For features that can't be emulated: + +1. **Preview in cloud** - Deploy to dev environment for testing +2. **Mock externals** - Use mocks for cloud-specific APIs +3. **Integration tests** - Test cloud features in CI/CD pipelines + + + Learn how to deploy to cloud environments for testing + + +## Learn More + + + + Get started with local development + + + + Complete CLI reference for `suga dev` + + + + Configure databases and connection strings + + + + Deploy to cloud after local testing + + diff --git a/docs/core/overview.mdx b/docs/core/overview.mdx new file mode 100644 index 00000000..88a8d88a --- /dev/null +++ b/docs/core/overview.mdx @@ -0,0 +1,303 @@ +--- +title: "Core Concepts Overview" +sidebarTitle: "Overview" +description: "Understanding Suga's architecture and core concepts" +--- + +Suga is built on a clear separation of concerns that enables both developer productivity and platform governance. Understanding these core concepts will help you make the most of the platform. + +## The Suga Architecture + +Suga operates through three key layers that work together to transform your application designs into deployed infrastructure: + +```mermaid +graph TB + A[Projects
What you want] --> D[Platforms
How to build it] + D --> B[Plugins
Cloud resources] + B --> C[Terraform
Deployed infrastructure] + + style A fill:#2BC65F,stroke:#1E9A47,stroke-width:2px,color:#fff,font-weight:500 + style D fill:#25B355,stroke:#1E9A47,stroke-width:2px,color:#fff,font-weight:500 + style B fill:#1E9A47,stroke:#178A3D,stroke-width:2px,color:#fff,font-weight:500 + style C fill:#178A3D,stroke:#125E2F,stroke-width:2px,color:#fff,font-weight:500 +``` + +### 1. Projects: What You Want + +[Projects](/core/projects) are your application specifications - declarative YAML files that describe what your application needs: + +- **Services** - Application containers that run your code +- **Buckets** - Cloud storage for files and assets +- **Databases** - PostgreSQL databases for structured data +- **Entrypoints** - HTTP routing and CDN configuration + +Projects are **deployment-agnostic** - they describe requirements without specifying how they're implemented. + +```yaml title="Example: A simple web application" +name: my-app +target: suga/aws@1 # Or any other target you like + +services: + api: + subtype: lambda + dev: + script: npm run dev + +buckets: + uploads: + subtype: s3 + access: + api: [read, write] + +entrypoints: + web: + subtype: cloudfront + routes: + /api/: + name: api +``` + +### 2. Platforms: How to Build It + +[Platforms](/core/platforms) are blueprints that map your project's abstract resources to specific cloud implementations. They define: + +- Which cloud services to use (Lambda vs Fargate, S3 vs Cloud Storage) +- How to configure those services (memory, CPU, networking) +- Security policies and access controls +- Infrastructure dependencies (VPCs, load balancers) + +Platform teams create and publish platforms to enforce organizational standards while delivering seamless developer experiences. + +### 3. Plugins: Cloud Resources + +[Plugins](/core/plugins) are the lowest-level building blocks - reusable Terraform modules that provision specific cloud resources. Each plugin contains: + +- **Terraform module** - Infrastructure-as-code for a specific cloud service +- **Input schema** - Configuration properties the module accepts +- **Runtime adapter** (optional) - Go code that translates SDK calls to cloud APIs + +Platforms compose multiple plugins to create complete deployment targets. + +## The Suga Workflow + +Understanding how these pieces work together: + + + + Create your project using the visual editor or by editing `suga.yaml` directly. + + ```bash + suga edit # Visual editor + # or edit suga.yaml manually + ``` + + + + Test your application with emulated cloud services running locally. + + ```bash + suga dev + ``` + + Local development provides: + - Hot reloading for code changes, using watcher dev scripts + - Emulated buckets, entrypoints, and databases + - Fast iteration without cloud costs + + + + Build Terraform infrastructure from your project and target platform. + + ```bash + suga build + ``` + + This process: + 1. Loads your project specification (`suga.yaml`) + 2. Fetches the target platform definition + 3. Maps each resource to appropriate plugins + 4. Generates Terraform modules with proper configuration + 5. Creates IAM policies for service access + 6. Outputs a complete Terraform stack + + + + Deploy the generated Terraform to your cloud provider. + + ```bash + cd terraform/stacks/my-app + terraform init + terraform apply + ``` + + Standard Terraform workflow - you have full control over deployment timing, preview changes with `terraform plan`, and manage state as you normally would. + + + +## Key Concepts + +### Declarative Infrastructure + +Suga uses a declarative approach - you specify **what** you want, not **how** to create it. + +```yaml title="Declarative: What you want" +buckets: + uploads: + access: + api: [read, write] +``` + +Suga handles the **how**: +- Creates S3 bucket (AWS) or Cloud Storage bucket (GCP) +- Configures IAM policies for service access +- Sets up lifecycle rules and encryption +- Generates connection configuration + +### Separation of Concerns + +Suga maintains clear boundaries between different responsibilities: + +| Layer | Responsibility | Owned By | +|-------|---------------|----------| +| **Project** | Application requirements | Developers | +| **Platform** | Implementation strategy | Platform teams | +| **Plugin** | Cloud resource provisioning | Plugin authors | +| **Terraform** | Infrastructure deployment | DevOps/SRE | + +This separation enables: +- Developers to focus on application needs +- Platform teams to enforce standards +- Infrastructure to evolve independently +- Teams to work in parallel + +### Infrastructure as Configuration + +Unlike infrastructure as **code** (where you write Terraform/Pulumi), Suga treats infrastructure as **configuration**: + +- **Configuration** - High-level, declarative, human-readable +- **Code** - Generated automatically, optimized, consistent + +You edit configuration, Suga generates code. + +### Platform-Driven Governance + +Platforms act as governance boundaries: + +```yaml title="Developer specifies requirements" +services: + api: + # I need a service +``` + +```yaml title="Platform enforces standards" +services: + lambda: + properties: + memory: 512 # Organization-mandated memory + timeout: 10 # Organization-mandated timeout + identities: + - plugin: iam-role # Auto-generated IAM with least privilege +``` + +Platform teams control: +- Which cloud services are available +- How they're configured by default +- What developers can customize +- Security and compliance policies + +### Runtime Abstraction (Optional) + +If you use Suga's generated SDKs, the same code works everywhere: + +```typescript title="Cloud-agnostic code" +import { SugaClient } from './suga/client'; + +const suga = new SugaClient(); + +// Works locally with suga dev +// Works on AWS Lambda with S3 +// Works on GCP Cloud Run with Cloud Storage +await suga.uploads.write('file.txt', data); +``` + +Plugins provide runtime adapters that translate abstract operations to cloud-specific APIs. + +## Design Principles + +Suga is built on several core principles: + +### 1. Visual-First Design + +Infrastructure should be visual and intuitive. The visual editor provides: +- Drag-and-drop resource creation +- Visual connections show relationships +- Real-time validation +- AI-assisted architecture design +- Automatic YAML generation + +### 2. Local Development First + +Developers should be able to work entirely locally without cloud access: +- Emulated cloud services +- Fast iteration cycles +- No cloud costs during development +- Consistent behavior between local and production + +### 3. Standard Artifacts + +Suga generates standard, transparent artifacts: +- **Terraform HCL** - Not proprietary formats +- **Standard providers** - AWS, GCP, Azure Terraform providers +- **No magic** - Generated Terraform is readable and customizable + +### 4. Progressive Enhancement + +Start simple, add complexity as needed: +- Begin with default platform configurations +- Customize as requirements grow +- Create custom platforms for specialized needs +- Build custom plugins for unique resources + +### 5. Team Scalability + +Enable teams to work independently while maintaining consistency: +- Platform teams publish reusable blueprints +- Development teams consume platforms +- Plugin authors create building blocks +- Clear interfaces between layers + +## Next Steps + +Now that you understand Suga's core concepts, dive deeper into each component: + + + + Learn how to define application requirements + + + + Understand platform blueprints and governance + + + + Explore the building blocks of infrastructure + + + + See how Suga transforms projects into Terraform + + + + Master local development workflow + + + + Understand deployment and operations + + + +Or jump straight to building: + + + Follow the quickstart guide to deploy an application end-to-end + diff --git a/docs/platforms.mdx b/docs/core/platforms.mdx similarity index 96% rename from docs/platforms.mdx rename to docs/core/platforms.mdx index 724af304..4b0f5510 100644 --- a/docs/platforms.mdx +++ b/docs/core/platforms.mdx @@ -1,9 +1,9 @@ --- -title: "Platforms Overview" +title: "Platforms" description: "Understanding Suga's platforms and ecosystem" --- -Platforms in Suga solve a critical challenge: delivering the seamless developer experience of modern deployment platforms while maintaining enterprise control and flexibility. They're blueprints that transform application specifications ([Projects](/projects)) into deployable infrastructure by generating Terraform HCL and providing runtime adapters that translate abstract resource operations into cloud-specific API calls. +Platforms in Suga solve a critical challenge: delivering the seamless developer experience of modern deployment platforms while maintaining enterprise control and flexibility. They're blueprints that transform application specifications ([Projects](/core/projects)) into deployable infrastructure by generating Terraform HCL and providing runtime adapters that translate abstract resource operations into cloud-specific API calls. Platform teams can create, customize, and govern these distributed packages to provide developers with instant deployments, automatic scaling, and zero-configuration infrastructure, while maintaining full control over security, compliance, and infrastructure standards. @@ -68,7 +68,7 @@ Platforms operate through two key mechanisms: **Infrastructure Generation** and ### Infrastructure Generation -When you run `suga build`, Suga uses your target platform to transform your [Project](/projects) specification into cloud-specific Terraform HCL (called stacks). This process: +When you run `suga build`, Suga uses your target platform to transform your [Project](/core/projects) specification into cloud-specific Terraform HCL (called stacks). This process: 1. **Maps abstract resources** - Takes your high-level resource definitions (services, buckets, databases) and selects appropriate cloud implementations 2. **Generates Terraform modules** - Creates infrastructure-as-code that provisions actual cloud resources with proper networking, security, and permissions diff --git a/docs/core/plugins.mdx b/docs/core/plugins.mdx new file mode 100644 index 00000000..d8e2d039 --- /dev/null +++ b/docs/core/plugins.mdx @@ -0,0 +1,279 @@ +--- +title: "Plugins" +description: "Understanding Suga's plugin system - the building blocks of cloud infrastructure" +--- + +Plugins are the fundamental building blocks of Suga platforms. Each plugin is a self-contained, reusable unit that knows how to provision and manage a specific type of cloud resource. Platforms compose multiple plugins to create complete deployment targets. + +## What is a Plugin? + +A plugin is a package containing: + +1. **Terraform Module** - Infrastructure-as-code that provisions cloud resources +2. **Manifest** - Schema defining configuration properties and outputs +3. **Runtime Adapter** (optional) - Go code that translates abstract SDK operations into cloud-specific API calls + +``` +plugin-directory/ +├── manifest.yaml # Plugin schema and metadata +├── main.tf # Terraform resources +├── variables.tf # Input variables +├── outputs.tf # Output values +└── runtime/ # Optional runtime adapters + ├── client.go # SDK client implementation + └── operations.go # Cloud-specific operations +``` + +## Plugin Types + +Suga uses plugins for different types of infrastructure: + +### Resource Plugins + +Map to application resources defined in projects: + +- **Service plugins** - Compute resources (Lambda, Fargate, Cloud Run) +- **Bucket plugins** - Object storage (S3, Cloud Storage) +- **Database plugins** - SQL databases (RDS, Cloud SQL, Neon) +- **Entrypoint plugins** - CDN and routing (CloudFront, Cloud CDN) + +### Identity Plugins + +Provide authentication and authorization: + +- **IAM role plugins** - AWS IAM roles +- **Service account plugins** - GCP service accounts +- Auto-generated based on resource access patterns + +### Infrastructure Plugins + +Provide foundational cloud resources: + +- **VPC plugins** - Network configuration +- **Load balancer plugins** - Traffic distribution +- **Security group plugins** - Firewall rules + +## How Platforms Use Plugins + +Platforms reference plugins in their resource blueprints: + +```yaml title="Platform blueprint using plugins" +services: + lambda: + source: + library: suga/aws + plugin: lambda + properties: + memory: ${self.memory} + timeout: ${self.timeout} + variables: + memory: + type: number + default: 512 + timeout: + type: number + default: 10 + identities: + - source: + library: suga/aws + plugin: iam-role +``` + +When you run `suga build`, the platform: + +1. Maps your project resources to plugin blueprints +2. Resolves property values and variables +3. Generates Terraform module calls +4. Configures dependencies and outputs + +## Official Plugin Libraries + +Suga maintains official plugin libraries for major cloud providers: + +### AWS Plugin Library (`suga/aws`) + +| Plugin | Purpose | Provisions | +|--------|---------|-----------| +| `lambda` | Serverless compute | AWS Lambda function + ECR repository | +| `fargate` | Container compute | ECS Fargate service + ECR + ALB target | +| `s3-bucket` | Object storage | S3 bucket with encryption and policies | +| `cloudfront` | CDN and routing | CloudFront distribution + WAF (optional) | +| `iam-role` | Service identity | IAM role with policies | +| `vpc` | Network foundation | VPC with subnets and NAT gateway | +| `loadbalancer` | Traffic distribution | Application Load Balancer | +| `security-group-rule` | Network security | Security group rules | + +### GCP Plugin Library (`suga/gcp`) + +| Plugin | Purpose | Provisions | +|--------|---------|-----------| +| `cloudrun` | Serverless containers | Cloud Run service + Artifact Registry | +| `storage-bucket` | Object storage | Cloud Storage bucket with policies | +| `cdn` | CDN and routing | Cloud Load Balancer + Cloud CDN | +| `service-account` | Service identity | Service account with IAM bindings | + +### Neon Plugin Library (`suga/neon`) + +| Plugin | Purpose | Provisions | +|--------|---------|-----------| +| `database` | PostgreSQL database | Neon database with branch support | + +## Plugin Configuration + +Plugins accept configuration through properties defined in their manifests: + +### Input Properties + +Configure how resources are provisioned: + +```yaml title="Lambda plugin properties" +properties: + memory: 512 # Memory allocation in MB + timeout: 10 # Execution timeout in seconds + ephemeral_storage: 512 # /tmp directory size in MB +``` + +These map directly to Terraform module variables. + +### Property Types + +Plugins support various property types: + +- **Primitives** - `string`, `number`, `bool` +- **Collections** - `list(string)`, `map(string)` +- **Objects** - Complex nested structures +- **References** - `${var.name}`, `${self.property}`, `${infra.component.output}` + +### Variable References + +Properties can reference platform or blueprint variables: + +```yaml title="Using variable references" +properties: + memory: ${self.memory} # Blueprint variable + project_id: ${var.project_id} # Platform variable + vpc_id: ${infra.aws_vpc.vpc_id} # Infrastructure output +``` + +## Plugin Outputs + +Plugins expose outputs that other resources can reference: + +```hcl title="Lambda plugin outputs" +output "function_arn" { + description = "ARN of the Lambda function" + value = aws_lambda_function.main.arn +} + +output "function_name" { + description = "Name of the Lambda function" + value = aws_lambda_function.main.function_name +} +``` + +These outputs are available to: +- Identity plugins (for IAM policy generation) +- Other infrastructure components +- Platform routing configuration + +## Runtime Adapters + +For plugins that provide SDK functionality (services, buckets), runtime adapters translate abstract operations into cloud-specific API calls. + +### Adapter Structure + +```go title="Example runtime adapter" +package runtime + +// Client provides cloud-specific implementations +type Client struct { + s3Client *s3.Client +} + +// Write implements the bucket write operation +func (c *Client) Write(ctx context.Context, key string, data []byte) error { + _, err := c.s3Client.PutObject(ctx, &s3.PutObjectInput{ + Bucket: aws.String(c.bucketName), + Key: aws.String(key), + Body: bytes.NewReader(data), + }) + return err +} +``` + +### How Adapters Work + +When you use Suga's generated SDK: + +```typescript title="Application code" +await suga.uploads.write('file.txt', data); +``` + +The runtime: +1. Identifies the plugin used for the `uploads` bucket +2. Loads the plugin's runtime adapter +3. Calls the adapter's `Write` method with cloud credentials +4. Adapter translates to cloud-specific API call (S3, Cloud Storage, etc.) + +## Plugin Versioning + +Plugins are versioned and distributed through plugin libraries: + +```yaml title="Platform specifies plugin versions" +libraries: + suga/aws: v0.0.4 + suga/neon: v0.0.2 +``` + +When you build your application: +- Suga fetches the specified plugin versions +- Generates Terraform using those plugin modules +- Ensures consistent deployments across environments + +## Plugin Discovery + +Browse available plugins: + + + Explore official and community plugins in the platform browser + + +## Creating Custom Plugins + +Organizations can create custom plugins for: + +- **Proprietary services** - Internal APIs and systems +- **Specialized configurations** - Custom cloud resource setups +- **Third-party integrations** - SaaS services and external APIs + + + Learn how to create custom plugins for your organization + + +### Plugin Development Workflow + +1. **Create Terraform module** - Define cloud resources +2. **Write manifest** - Specify schema and metadata +3. **Add runtime adapter** (optional) - Implement SDK operations +4. **Test locally** - Use with local projects +5. **Publish** - Share within your organization + +## Learn More + + + + Learn how platforms compose plugins + + + + Create custom plugins for your needs + + + + See how plugins generate Terraform + + + + Explore available plugins + + diff --git a/docs/projects.mdx b/docs/core/projects.mdx similarity index 96% rename from docs/projects.mdx rename to docs/core/projects.mdx index 4f1d5e5a..84804347 100644 --- a/docs/projects.mdx +++ b/docs/core/projects.mdx @@ -1,5 +1,5 @@ --- -title: "Projects Overview" +title: "Projects" description: "Understanding Suga projects - the application specifications that define your cloud architecture" --- @@ -7,7 +7,7 @@ Projects in Suga are application specifications that define your cloud architect ## What is a Project? -A Suga project is defined by a `suga.yaml` file that describes your application's infrastructure requirements using cloud-agnostic resource types. When combined with a [Platform](/platforms), this specification gets transformed into deployable cloud infrastructure. +A Suga project is defined by a `suga.yaml` file that describes your application's infrastructure requirements using cloud-agnostic resource types. When combined with a [Platform](/core/platforms), this specification gets transformed into deployable cloud infrastructure. @@ -40,6 +40,7 @@ description: An example web application with storage services: app: + subtype: lambda dev: script: npm run dev path: ./app @@ -50,6 +51,7 @@ services: buckets: bucket: + subtype: s3 access: app: - read @@ -57,6 +59,7 @@ buckets: entrypoints: api: + subtype: cloudfront routes: /: name: frontend @@ -100,6 +103,7 @@ Services are your application containers that handle business logic: ```yaml title="Service definitions" services: app: + subtype: lambda env: EXT_URL: https://somewhere.example.com container: @@ -110,6 +114,7 @@ services: script: npm run dev worker: + subtype: fargate container: image: id: "my-registry/worker:latest" diff --git a/docs/deploy/aws.mdx b/docs/deploy/aws.mdx new file mode 100644 index 00000000..2360336a --- /dev/null +++ b/docs/deploy/aws.mdx @@ -0,0 +1,51 @@ +--- +title: "AWS Deployment" +description: "Deploy Suga applications to Amazon Web Services" +--- + +Deploy Suga applications to AWS using Lambda, Fargate, S3, and CloudFront. + +## Platform-Specific Requirements + +The exact setup steps (account creation, IAM roles, etc.) depend on which Suga platform you're using. Each platform has specific requirements documented in the platform browser. + + + View available platforms and their setup requirements + + +Generally, deployments to AWS will require the following. + +## Prerequisites + +- **AWS CLI** - [Installation guide](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) +- **Terraform** - [Installation guide](https://developer.hashicorp.com/terraform/install) +- **Suga CLI** - See [Installation](/installation) + +## Quick Start + +```bash +# Build your application +suga build + +# Navigate to generated stack +cd terraform/stacks/my-app +``` + +Create provider configuration: + +```hcl title="provider.tf" +provider "aws" { + region = "us-west-2" +} +``` + +Deploy: + +```bash +terraform init +terraform apply +``` + + + See the full deployment workflow + diff --git a/docs/deploy/azure.mdx b/docs/deploy/azure.mdx new file mode 100644 index 00000000..adf81b08 --- /dev/null +++ b/docs/deploy/azure.mdx @@ -0,0 +1,14 @@ +--- +title: "Azure Deployment" +description: "Deploy Suga applications to Microsoft Azure" +--- + +Azure support is coming soon. + + + Azure platform development is in progress. Check back soon for updates. + + +## Interested in Azure Support? + +Contact [support@addsuga.com](mailto:support@addsuga.com) to express interest or get notified when Azure support is available. diff --git a/docs/deploy/gcp.mdx b/docs/deploy/gcp.mdx new file mode 100644 index 00000000..911e68c8 --- /dev/null +++ b/docs/deploy/gcp.mdx @@ -0,0 +1,50 @@ +--- +title: "GCP Deployment" +description: "Deploy Suga applications to Google Cloud Platform" +--- + +Deploy Suga applications to GCP using Cloud Run, Cloud Storage, and Cloud CDN. + +## Platform-Specific Requirements + +The exact setup steps (project creation, API enablement, IAM roles, etc.) depend on which Suga platform you're using. Each platform has specific requirements documented in the platform browser. + + + View available platforms and their setup requirements + + +Generally, deployments to GCP will require the following. + +## Prerequisites + +- **Google Cloud CLI** - [Installation guide](https://cloud.google.com/sdk/docs/install) +- **Terraform** - [Installation guide](https://developer.hashicorp.com/terraform/install) +- **Suga CLI** - See [Installation](/installation) + +## Quick Start + +```bash +# Build your application +suga build + +# Navigate to generated stack +cd terraform/stacks/my-app +``` + +Configure required variables: + +```hcl title="terraform.tfvars" +project_id = "my-gcp-project" +region = "us-central1" +``` + +Deploy: + +```bash +terraform init +terraform apply +``` + + + See the full deployment workflow + \ No newline at end of file diff --git a/docs/deploy/overview.mdx b/docs/deploy/overview.mdx new file mode 100644 index 00000000..e26e9269 --- /dev/null +++ b/docs/deploy/overview.mdx @@ -0,0 +1,413 @@ +--- +title: "Deployment Overview" +sidebarTitle: "Overview" +description: "Understand how Suga applications are deployed to the cloud" +--- + +Deploying with Suga means running standard Terraform commands on the infrastructure generated by `suga build`. This page explains the deployment lifecycle, how to deploy to different environments, and best practices for production deployments. + +## Deployment Overview + +Suga's deployment model is transparent and uses standard tools: + +1. **Generate Terraform** - `suga build` creates Terraform modules +2. **Configure Provider** - Set up cloud provider credentials and configuration +3. **Initialize Terraform** - Download providers and modules +4. **Preview Changes** - Review what will be created/modified +5. **Apply Changes** - Deploy to your cloud provider +6. **Verify Deployment** - Test deployed resources + +## The Deployment Lifecycle + + + + Generate Terraform from your project: + + ```bash + suga build + ``` + + Output: + ``` + ✓ Terraform generated successfully + output written to terraform/stacks/my-app + + Next steps: + 1. Run cd terraform/stacks/my-app to move to the stack directory + 2. Initialize the stack terraform init -upgrade + 3. Optionally, preview with terraform plan + 4. Deploy with terraform apply + ``` + + + + Change to the generated Terraform directory: + + ```bash + cd terraform/stacks/my-app + ``` + + Contents: + ``` + my-app/ + ├── cdk.tf.json # Main Terraform Entrypoint + └── .terraform/ # Plugin Terraform modules + └── modules/ + ├── api/ + ├── api_image/ + ├── uploads_bucket/ + └── ... + ``` + + + + Set up provider configuration and credentials: + + + + ```bash + # Configure credentials + aws configure + ``` + + Create provider configuration: + + ```hcl title="provider.tf" + provider "aws" { + region = "us-west-2" + } + ``` + + + + ```bash + # Configure credentials + gcloud auth application-default login + ``` + + Set required variables: + + ```hcl title="terraform.tfvars" + project_id = "my-gcp-project" + region = "us-central1" + ``` + + + + + Files like `provider.tf` and `terraform.tfvars` are preserved across builds and won't be overwritten. + + + + + Download providers and modules: + + ```bash + terraform init -upgrade + ``` + + This downloads: + - Cloud provider Terraform providers (AWS, GCP, etc.) + - Plugin modules referenced by your platform + - Backend configuration (if configured) + + + + Review what Terraform will create: + + ```bash + terraform plan + ``` + + Output shows: + - Resources to be created (`+`) + - Resources to be modified (`~`) + - Resources to be deleted (`-`) + + + Always review the plan carefully before applying, especially in production environments. + + + + + Apply the Terraform configuration: + + ```bash + terraform apply + ``` + + Terraform will: + 1. Show the plan again + 2. Ask for confirmation + 3. Create resources in your cloud account + 4. Save state to track resources + + ```bash + Apply complete! Resources: 15 added, 0 changed, 0 destroyed. + + Outputs: + entrypoint_web_url = "https://d123abc.cloudfront.net" + service_api_function_name = "my-app-api" + ``` + + + + Test your deployed application: + + ```bash + # Get the entrypoint URL from outputs + terraform output entrypoint_web_url + + # Test the endpoint + curl https://d123abc.cloudfront.net/api/health + ``` + + + +## Managing Deployments + +### Updating Your Application + +When you make changes to your project: + +1. **Rebuild Terraform:** + ```bash + suga build + ``` + +2. **Preview changes:** + ```bash + cd terraform/stacks/my-app + terraform plan + ``` + +3. **Apply updates:** + ```bash + terraform apply + ``` + +Terraform intelligently updates only what changed: +- Modified services are redeployed +- New resources are created +- Removed resources are deleted +- Unchanged resources remain untouched + +### Deploying Code Updates + +When you update service code without changing infrastructure: + +```bash +# Simply re-run terraform apply +cd terraform/stacks/my-app +terraform apply +``` + +Terraform automatically: +1. Builds new container images from your updated code +2. Pushes images to the container registry (ECR, Artifact Registry, etc.) +3. Updates services to use the new images +4. Handles rolling deployments with zero downtime + +No manual Docker commands needed - the generated Terraform includes container build and push logic. + + + CI/CD pipelines typically automate this by running `terraform apply` on every commit. See the [CI/CD Authentication Guide](/guides/cicd-authentication) for details. + + +### Rolling Back + +If a deployment causes issues, roll back: + +```bash +# Revert code changes +git revert + +# Rebuild Terraform +suga build + +# Apply previous configuration +cd terraform/stacks/my-app +terraform apply +``` + +Or roll back to a previous Terraform state: + +```bash +# List state backups +terraform state list + +# If using versioned state backend, restore previous version +# (AWS S3, GCS, Terraform Cloud all support versioning) +``` + +### Destroying Resources + +When you're done with a deployment: + +```bash +cd terraform/stacks/my-app +terraform destroy +``` + + + `terraform destroy` permanently deletes all cloud resources. Databases, buckets, and all data will be lost. Use with extreme caution, especially in production. + + +## Multi-Environment Deployments + +Deploy the same application to multiple environments (dev, staging, production) using Terraform workspaces and environment-specific variable files. This allows you to maintain a single infrastructure definition while customizing configuration per environment. + + + Learn how to manage multiple environments with Terraform workspaces and variables + + +## Cloud Provider Setup + +Each cloud provider requires specific credentials and permissions. Detailed setup instructions including required permissions, authentication methods, and provider configuration are available in the provider-specific guides: + + + + AWS credentials, IAM permissions, and configuration + + + + GCP service accounts, permissions, and configuration + + + + Azure credentials, RBAC, and configuration + + + +## Terraform State Management + +Terraform state tracks deployed resources and must be managed carefully. By default, state is stored locally, which is suitable for personal projects but not recommended for teams. For production deployments, use a remote backend for state locking, versioning, and team collaboration. + + + Complete guide to configuring remote state backends (S3, GCS, Terraform Cloud) + + +## CI/CD Integration + +Automate deployments with CI/CD pipelines to build infrastructure and deploy on every commit. Common patterns include GitHub Actions, GitLab CI, CircleCI, and Jenkins. + + + Learn how to authenticate Suga in CI/CD pipelines with example workflows + + +## Best Practices + +### 1. Always Preview Before Applying + +```bash +terraform plan # Review changes +terraform apply # Only after reviewing +``` + +### 2. Use Remote State for Teams + +Configure a remote backend for team deployments. See the [Terraform Backend Configuration](/guides/terraform-backend-config) guide. + +### 3. Separate Environments + +Use Terraform workspaces or separate state files. See the [Environment Management](/deploy/terraform-configuration#environment-management) docs. + +### 4. Version Control Everything + +Commit generated Terraform to git: + +```bash +git add terraform/ +git commit -m "Update infrastructure" +``` + +### 5. Test in Non-Production First + +Always deploy to dev/staging before production: + +```bash +# Deploy to dev +terraform workspace select dev +terraform apply + +# Test thoroughly +# Then deploy to prod +terraform workspace select prod +terraform apply +``` + +### 6. Use Terraform Variables for Configuration + +Use variable files for environment-specific configuration. See the [Terraform Configuration](/deploy/terraform-configuration) guide. + +### 7. Monitor Deployments + +Set up monitoring for deployed resources: +- CloudWatch (AWS) +- Cloud Monitoring (GCP) +- Application Performance Monitoring (APM) tools + +### 8. Document Your Deployments + +Maintain deployment documentation: + +```markdown title="DEPLOYMENT.md" +## Production Deployment + +1. Ensure tests pass: `npm test` +2. Build infrastructure: `suga build` +3. Review changes: `terraform plan` +4. Deploy: `terraform apply` +5. Verify: `curl https://api.example.com/health` +6. Monitor: Check CloudWatch dashboard +``` + +## Troubleshooting + +### Common Deployment Issues + +**"No valid credential sources found"** + +Solution: Configure cloud provider credentials properly. + +**"Resource already exists"** + +Solution: Import existing resource into Terraform state: +```bash +terraform import . +``` + +**"State lock timeout"** + +Solution: Another apply is running, or a previous one crashed. Release lock: +```bash +terraform force-unlock +``` + +**"Plan shows unwanted changes"** + +Solution: Check for drift between state and actual resources: +```bash +terraform refresh +terraform plan +``` + +## Learn More + + + + Understand how Terraform is generated + + + + Learn how to manage multiple environments with Terraform workspaces and variables + + + + Best practices for Terraform configuration + + + + How to develop applications locally with Suga + + diff --git a/docs/deploy/terraform-configuration.mdx b/docs/deploy/terraform-configuration.mdx new file mode 100644 index 00000000..96ba1cb0 --- /dev/null +++ b/docs/deploy/terraform-configuration.mdx @@ -0,0 +1,43 @@ +--- +title: "Terraform Configuration" +description: "Configure Terraform backends, state management, and variables" +--- + +## Remote State Backends + + + See the complete backend configuration guide + + +## Environment Management + +Manage multiple environments using [Terraform workspaces](https://developer.hashicorp.com/terraform/language/state/workspaces) and variable files. + +## Using Workspaces + +```bash +# Create workspaces +terraform workspace new dev +terraform workspace new staging +terraform workspace new prod + +# Deploy to dev +terraform workspace select dev +terraform apply -var-file=environments/dev.tfvars + +# Deploy to prod +terraform workspace select prod +terraform apply -var-file=environments/prod.tfvars +``` + +## Environment-Specific Configuration + +```hcl title="environments/dev.tfvars" +services_api_memory = 512 +services_api_timeout = 10 +``` + +```hcl title="environments/prod.tfvars" +services_api_memory = 2048 +services_api_timeout = 30 +``` diff --git a/docs/develop/access-control.mdx b/docs/develop/access-control.mdx new file mode 100644 index 00000000..de83f9da --- /dev/null +++ b/docs/develop/access-control.mdx @@ -0,0 +1,120 @@ +--- +title: "Access Control" +description: "Managing permissions and security in Suga applications" +--- + +Suga's access control model defines which services can access which resources, automatically generating appropriate IAM policies or service account permissions. + +![temp](/images/develop/access-control/service-to-bucket-access-control.png) + +## How Access Control Works + +Access is granted through the `access` property on resources, which can be modified in your project's `suga.yaml` or through the visual editor with the `suga edit` CLI command. + +```yaml +services: + api: ... + worker: ... +buckets: + uploads: + subtype: s3 + access: + api: [read, write] # API service can read and write + worker: [read, delete] # Worker service can read and delete + +databases: + main: + subtype: rds + access: + api: [query] # API service can query database +``` + +When you deploy, Suga generates: +- **IAM policies** (AWS) with least-privilege permissions +- **Service account bindings** (GCP) with appropriate roles +- **Network security rules** allowing service-to-resource communication + +## Permission Types + +### Bucket Permissions + +- `read` - Download/read objects +- `write` - Upload/write objects +- `delete` - Delete objects +- `all` - Shorthand for read, write, delete + +```yaml +buckets: + data: + subtype: s3 + access: + uploader: [write] + processor: [read, delete] + api: [read] +``` + +### Database Permissions + +- `query` - Full SQL access (SELECT, INSERT, UPDATE, DELETE) + +```yaml +databases: + main: + subtype: rds + access: + api: [query] + analytics: [query] +``` + +## Least Privilege + +Suga encourages and follows the principle of least privilege: +- By default, services cannot access other resources +- Services only get permissions they need +- No wildcards or overly broad policies +- Separate identities per service + +When using the standard Suga AWS Platforms (`suga/aws`), here is an example of the kind of IAM policy that will be generated: + +```json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:GetObject", + "s3:PutObject" + ], + "Resource": "arn:aws:s3:::my-app-uploads/*" + } + ] +} +``` + + + If you use your own Suga [resource plugins](/core/plugins), you're free to construct the IAM, roles, etc. as you see fit. + + +## Best Practices + +1. **Grant minimum permissions** - Only what each service needs +2. **Separate services** - Different services for different roles +3. **Review access patterns** - Regularly audit who accesses what +4. **Use read-only when possible** - Many services only need read access + +## Learn More + + + + Service configuration + + + + Bucket permissions + + + + Database access + + diff --git a/docs/develop/buckets.mdx b/docs/develop/buckets.mdx new file mode 100644 index 00000000..7f1a249a --- /dev/null +++ b/docs/develop/buckets.mdx @@ -0,0 +1,169 @@ +--- +title: "Buckets" +description: "Object storage for files, images, and assets" +--- + +Buckets provide cloud object storage for your application - think files, images, videos, documents, and other unstructured data. + +## What is a Bucket? + +A bucket is object storage that: +- **Stores files** - Any file type, any size +- **Configurable access** - Set read, write, delete permissions +- **Scales automatically** - No capacity planning needed +- **Works everywhere** - Same interface locally and in production + +```yaml title="Basic bucket definition" +buckets: + uploads: + subtype: # your choice, from target platform + access: + api: [read, write, delete] + profile-images: + subtype: # your choice, from target platform + access: + api: [read, write] + frontend: [read] +``` + +## Bucket Configuration + +### Access Control + +Grant services access to buckets: + +```yaml +buckets: + uploads: + subtype: # your choice, from target platform + access: + api: [read, write, delete] # Full access + worker: [read, delete] # Read and delete only + frontend: [read] # Read-only +``` + +**Permission Types:** +- `read` - Download/read files +- `write` - Upload/write files +- `delete` - Delete files +- `all` - Shorthand for read, write, delete + +### Content Path (Static Files) + +Deploy static files to a bucket: + +```yaml +buckets: + frontend: + subtype: # your choice, from target platform + content_path: ./build # Deploy React/Vue/Angular build + +entrypoints: + web: + subtype: # your choice, from target platform + routes: + /: frontend # Serve static files from bucket +``` + +When you deploy, files from `./build` are uploaded to the bucket. + +## Using Buckets in Code + +With Suga's generated SDK: + + + + ```typescript + import { SugaClient } from './suga/client'; + + const suga = new SugaClient(); + + // Write file + await suga.uploads.write('path/to/file.txt', Buffer.from('data')); + + // Read file + const data = await suga.uploads.read('path/to/file.txt'); + + // Delete file + await suga.uploads.delete('path/to/file.txt'); + ``` + + + + ```python + from suga.client import SugaClient + + suga = SugaClient() + + # Write file + suga.uploads.write('path/to/file.txt', b'data') + + # Read file + data = suga.uploads.read('path/to/file.txt') + + # Delete file + suga.uploads.delete('path/to/file.txt') + ``` + + + + ```go + import "myapp/suga" + + client, _ := suga.NewClient() + + // Write file + client.Uploads.Write("path/to/file.txt", []byte("data")) + + // Read file + data, _ := client.Uploads.Read("path/to/file.txt") + + // Delete file + client.Uploads.Delete("path/to/file.txt") + ``` + + + + + Learn how to access resources from your service code + + +## Local Development + +During `suga dev`, buckets are emulated using the filesystem: + +``` +.suga/ +└── buckets/ + └── uploads/ + └── file.txt +``` + +You can: +- View files in `.suga/buckets/{bucket-name}/` +- Seed buckets by placing files there +- Test bucket operations without cloud access + + + Learn how to develop buckets locally with Suga + + +## Learn More + + + + Complete API reference + + + + Permission management + + + + Deploy static websites + + + + Test buckets locally + + diff --git a/docs/develop/databases.mdx b/docs/develop/databases.mdx new file mode 100644 index 00000000..0bbab59d --- /dev/null +++ b/docs/develop/databases.mdx @@ -0,0 +1,284 @@ +--- +title: "Databases" +description: "PostgreSQL databases for structured data" +--- + +Databases provide persistent SQL storage for your application's structured data. + +## What is a Database? + +A database in Suga is a PostgreSQL database that: +- **Stores structured data** - Tables, relations, indexes +- **Provides SQL access** - Full PostgreSQL compatibility +- **Scales automatically** - Managed database service +- **Integrates with services** - Automatic connection configuration + +```yaml title="Basic database" +databases: + main: + subtype: # your choice, from target platform + access: + api: [query] + worker: [query] +``` + +## Database Configuration + +### Access Control and Connection Strings + +When you grant a service access to a database, Suga automatically injects the database connection string into that service's environment variables: + +```yaml title="Database with environment variable injection" +databases: + main: + subtype: # your choice, from target platform + access: + api: [query] + worker: [query] + env_var_key: DATABASE_URL # Connection string injected as DATABASE_URL +``` + +Services with access automatically receive: +- **Full connection string** - Including host, port, database name, and credentials +- **Environment variable** - Specified by `env_var_key` +- **Ready to use** - Works immediately with standard PostgreSQL libraries + +**Permission:** +- `query` - Full read/write SQL access + +### Multiple Databases + +When using multiple databases, each must have a unique `env_var_key` to avoid conflicts: + +```yaml title="Multiple databases with unique env vars" +databases: + users: + subtype: # your choice, from target platform + access: + api: [query] + env_var_key: USERS_DATABASE_URL + + products: + subtype: # your choice, from target platform + access: + api: [query] + env_var_key: PRODUCTS_DATABASE_URL + + orders: + subtype: # your choice, from target platform + access: + api: [query] + env_var_key: ORDERS_DATABASE_URL +``` + +Now the `api` service receives three separate connection strings: +- `USERS_DATABASE_URL` +- `PRODUCTS_DATABASE_URL` +- `ORDERS_DATABASE_URL` + + + Each database **must** have a unique `env_var_key` if the same service accesses multiple databases. Using the same key for different databases will cause conflicts. + + +## Using Databases in Code + +Access databases using standard PostgreSQL libraries with the automatically injected connection string: + + + + Install the PostgreSQL client: + ```bash + npm install pg + ``` + + Then develop like you normally would, using the `env_var_key` you defined in your `suga.yaml`. + ```typescript + import { Pool } from 'pg'; + + // Connection string automatically injected by Suga + const pool = new Pool({ + connectionString: process.env.DATABASE_URL + }); + + // Query database + const result = await pool.query( + 'SELECT * FROM users WHERE active = $1', + [true] + ); + const users = result.rows; + + // Insert data + await pool.query( + 'INSERT INTO users (name, email) VALUES ($1, $2)', + ['Alice', 'alice@example.com'] + ); + + // Update data + await pool.query( + 'UPDATE users SET name = $1 WHERE id = $2', + ['Bob', 1] + ); + ``` + + + + Install the PostgreSQL client: + ```bash + pip install psycopg2-binary + ``` + + Then develop like you normally would, using the `env_var_key` you defined in your `suga.yaml`. + ```python + import psycopg2 + import os + + # Connection string automatically injected by Suga + conn = psycopg2.connect(os.environ['DATABASE_URL']) + cursor = conn.cursor() + + # Query database + cursor.execute('SELECT * FROM users WHERE active = %s', [True]) + users = cursor.fetchall() + + # Insert data + cursor.execute( + 'INSERT INTO users (name, email) VALUES (%s, %s)', + ['Alice', 'alice@example.com'] + ) + conn.commit() + + # Update data + cursor.execute( + 'UPDATE users SET name = %s WHERE id = %s', + ['Bob', 1] + ) + conn.commit() + ``` + + + + Install the PostgreSQL client: + ```bash + go get github.com/jackc/pgx/v5/pgxpool + ``` + + Then develop like you normally would, using the `env_var_key` you defined in your `suga.yaml`. + ```go + import ( + "context" + "os" + "github.com/jackc/pgx/v5/pgxpool" + ) + + // Connection string automatically injected by Suga + pool, err := pgxpool.New(context.Background(), os.Getenv("DATABASE_URL")) + if err != nil { + panic(err) + } + defer pool.Close() + + // Query database + rows, err := pool.Query(context.Background(), + "SELECT * FROM users WHERE active = $1", true) + + // Insert data + _, err = pool.Exec(context.Background(), + "INSERT INTO users (name, email) VALUES ($1, $2)", + "Alice", "alice@example.com") + + // Update data + _, err = pool.Exec(context.Background(), + "UPDATE users SET name = $1 WHERE id = $2", + "Bob", 1) + ``` + + + +### Connection String Format + +The injected `DATABASE_URL` contains everything needed to connect: + +``` +postgresql://username:password@host:port/database?sslmode=require +``` + +This works with any PostgreSQL-compatible library or ORM (Prisma, TypeORM, SQLAlchemy, etc.): + + + + ```javascript title="prisma/schema.prisma" + datasource db { + provider = "postgresql" + url = env("DATABASE_URL") + } + ``` + + + + ```typescript + import { DataSource } from 'typeorm'; + + const dataSource = new DataSource({ + type: 'postgres', + url: process.env.DATABASE_URL, + entities: [User], + }); + ``` + + + + ```python + from sqlalchemy import create_engine + import os + + engine = create_engine(os.environ['DATABASE_URL']) + ``` + + + +## Database Migrations + +Run migrations as part of your deployment: + + + Learn how to manage database schema changes + + +## Local Development + +During `suga dev`, PostgreSQL databases run automatically with no manual setup required: + +- Suga starts a local PostgreSQL instance for each database +- Connection strings are injected into services via `env_var_key` +- Data persists in `.suga/databases/` between sessions +- Use the same PostgreSQL libraries and ORMs as production + +```bash +suga dev +``` + +Your services receive `DATABASE_URL` (or your custom `env_var_key`) automatically, making the same code work in both local development and production. + + + Learn more about local development with databases + + +## Learn More + + + + Complete API reference + + + + Schema management + + + + Local PostgreSQL during `suga dev` + + + + Permission management + + diff --git a/docs/develop/entrypoints.mdx b/docs/develop/entrypoints.mdx new file mode 100644 index 00000000..d2ba691e --- /dev/null +++ b/docs/develop/entrypoints.mdx @@ -0,0 +1,112 @@ +--- +title: "Entrypoints" +description: "HTTP routing and CDN configuration for exposing your application" +--- + +Entrypoints provide HTTP access to your application through CDN and routing configuration. They act as the front door to your services and static assets. + +## What is an Entrypoint? + +An entrypoint is a CDN + router that: +- **Routes HTTP requests** - To services or buckets based on URL paths +- **Provides HTTPS** - Automatic SSL/TLS termination +- **Caches responses** - CDN caching for performance +- **Handles scaling** - Automatically scales with traffic + +```yaml title="Basic entrypoint" +entrypoints: + web: + subtype: # your choice, from target platform + routes: + /api/: + name: api # Route /api/* to api service + /: + name: frontend # Route /* to frontend service +``` + +## Route Configuration + +Routes map URL paths to destinations: + +```yaml +entrypoints: + subtype: # your choice, from target platform + web: + routes: + /api/: + name: api-service # Service destination + /static/: + name: assets # Bucket destination + /: + name: frontend # Service destination +``` + +**Path Matching:** +- `/api/` - Matches `/api/*` (with trailing content) +- `/` - Matches all remaining paths + +Routes are evaluated in order - most specific first. + +## Custom Domains + + + Most entrypoints support custom domains, however, this functionality is [platform](/core/platforms.mdx) specific. + + For example, the `suga/aws` platform will generate Terraform Variables during `suga build`, which allow you to specify a custom domain per entrypoint. + + +## Common Patterns + +**API + Frontend:** +```yaml +entrypoints: + web: + subtype: # your choice, from target platform + routes: + /api/: + name: api + /: + name: frontend +``` + +**Microservices Gateway:** +```yaml +entrypoints: + gateway: + subtype: # your choice, from target platform + routes: + /users/: + name: users-service + /products/: + name: products-service + /orders/: + name: orders-service +``` + +**Static Site with API:** +```yaml +entrypoints: + web: + subtype: # your choice, from target platform + routes: + /api/: + name: api + /: + name: static-assets # Bucket with static files +``` + +## Learn More + + + + Static website hosting + + + + Route to static files in buckets + + + + Configure routing destinations + + diff --git a/docs/develop/overview.mdx b/docs/develop/overview.mdx new file mode 100644 index 00000000..4b162c14 --- /dev/null +++ b/docs/develop/overview.mdx @@ -0,0 +1,200 @@ +--- +title: "Development Overview" +sidebarTitle: "Overview" +description: "Understanding Suga's resource types and how to define your application architecture" +--- + +Suga applications are built from several core resource types that work together to create complete cloud applications. This page introduces these resources and explains how they interact. + +## Suga Resources + +Every Suga application can use these resource types: + + + + Application containers that run your code + + + + HTTP routing and CDN configuration + + + + Object storage for files and assets + + + + PostgreSQL databases for structured data + + + +## Resource Relationships + +Resources connect to form your application architecture: + +![Project Editor Diagram Example](/images/develop/app-diagram-example.png) + +## Defining Resources + +Resources are defined in `suga.yaml`: + +```yaml title="suga.yaml" +target: suga/aws@1 +name: my-app +description: My cloud application + +services: + # Define services here + +buckets: + # Define buckets here + +databases: + # Define databases here + +entrypoints: + # Define entrypoints here +``` + +### Using the Visual Editor + +The easiest way to define resources is with the visual editor, by running the `edit` command in your project directory: + +```bash +suga edit +``` + +The visual editor provides: +- **Drag-and-drop** resource creation, using the available resource from your chosen platform +- **Visual connections** to establish relationships and access +- **Property editors** for configurations of resources +- **Real-time validation** of your architecture and configuration +- **Automatic YAML sync** with bidirectional live update to your project's suga.yaml file +- **AI Assistant** that can collaborate with you on your design + +### Editing YAML Directly + +You can also edit `suga.yaml` directly: + +```yaml title="suga.yaml" +services: + api: + subtype: # your choice, from target platform + container: + docker: + dockerfile: Dockerfile + context: . + dev: + script: npm run dev +``` + +## Resource Naming + +Resource names must follow these rules: + +- **Lowercase letters and numbers** - `api`, `api2`, `frontend` +- **Underscores allowed** - `api_service`, `user_uploads` +- **Start with letter** - `api` (not `2api`) +- **No special characters** - Avoid `-`, `.`, `/`, etc. + + + Resource names typically become part of cloud resource identifiers. Choose names that are descriptive and unlikely to change. + + +## Resource Configuration + +Each resource type has unique configuration options; however, there are some common configuration options. + +### Subtypes + +Cloud provider like AWS provide many container and compute runtime options including EC2, ECS and Fargate, Lambda, EKS, and more. The list gets longer as you look to other cloud providers. + +The same is true for other resources like Buckets, which might use S3 on AWS, Cloud Storage on GCP, Blob Storage on Azure or another option like self-hosted Minio on Kubernetes. + +Suga helps you build applications that work well on any of these services without significant modifications to your application code. Reducing vendor lock-in and the cost of change. This allows you to migrate between services during development or as you better understand the performance, cost and other needs of your applications. + +The resource subtype in the `suga.yaml` file is how you tell Suga which specific service you want to use: + +```yaml title="Choose specific cloud service" +services: + api: + subtype: lambda # AWS Lambda (serverless) + worker: + subtype: fargate # AWS Fargate (containers) + +buckets: + uploads: + subtype: s3 # AWS S3 + +entrypoints: + web: + subtype: cloudfront # AWS CloudFront +``` + +The available subtypes depend on your target [platform](/core/platforms): +- `suga/aws@1` - Lambda, Fargate, S3, CloudFront +- `suga/gcp@1` - Cloud Run, Cloud Storage, Cloud CDN +- `you/custom@1` - Any other cloud or resources you like, including cross-cloud deployments + +### Access Control + +Resources can grant access to services: + +```yaml title="Grant service access to resources" +buckets: + uploads: + ... + access: + api: [read, write, delete] # API service can read/write/delete + frontend: [read] # Frontend can only read + +databases: + main: + ... + access: + api: [query] # API service can query the database +``` + +This generates appropriate IAM policies or service account permissions. + + + Learn more about access control patterns + + +## Accessing Resources from Code + +Once you've defined resources in your `suga.yaml`, Suga provides generated client libraries for cloud-agnostic resource access. The same code works locally with `suga dev` and in production across any cloud provider. + + + Learn about generated client libraries for buckets and resource access patterns + + +## Learn More + +Dive deeper into each resource type: + + + + Application containers and compute + + + + HTTP routing and CDN + + + + Object storage and file management + + + + PostgreSQL databases + + + + Security and permissions + + + + How Suga deploys applications + + diff --git a/docs/develop/services.mdx b/docs/develop/services.mdx new file mode 100644 index 00000000..e1e20e02 --- /dev/null +++ b/docs/develop/services.mdx @@ -0,0 +1,238 @@ +--- +title: "Services" +description: "Application containers that run your code" +--- + +Services are the compute layer of your Suga application - containers that run your application code and handle business logic. + +## What is a Service? + +A service is an application container that: +- **Runs your code** - Node.js, Python, Go, or any containerized application +- **Handles requests** - HTTP requests, background jobs, scheduled tasks +- **Accesses resources** - Buckets, databases, other services +- **Scales automatically** - Based on traffic (Lambda, Cloud Run) or configuration (Fargate) + +```yaml title="Basic service definition" +services: + api: + subtype: # your choice, from target platform + dev: + script: npm run dev + container: + docker: + dockerfile: Dockerfile + context: . + env: + EXT_URL: "https://example.com/api" +``` + +## Service Configuration + +### Development Script + +The `dev.script` tells Suga how to run your service locally: + +```yaml +services: + api: + subtype: # your choice, from target platform + dev: + script: npm run dev # Node.js + worker: + subtype: # your choice, from target platform + dev: + script: python main.py # Python + processor: + subtype: # your choice, from target platform + dev: + script: go run main.go # Go +``` + +During `suga dev`, this script runs and can automatically restart on code changes. + +### Container Configuration + +For production deployment, services need container configuration: + +**Using Dockerfile:** +```yaml +services: + api: + subtype: # your choice, from target platform + container: + docker: + dockerfile: Dockerfile + context: . +``` + +**Using Pre-built Image:** +```yaml +services: + api: + subtype: # your choice, from target platform + container: + image: + id: "my-registry/api:latest" +``` + +### Environment Variables + +Configure services with environment variables: + +```yaml +services: + api: + subtype: # your choice, from target platform + env: + DATABASE_URL: postgresql://... + REDIS_URL: redis://... + LOG_LEVEL: info + FEATURE_XYZ: "true" +``` + +There are a few reserved environment variables that should be avoided. These are `PORT` and environment variables with the prefix `SUGA_`. + +#### PORT environment variable + +In order to establish HTTP routes/requests Suga will automatically inject a `PORT` env var into each of your services, indicating which port it should start on. + +```typescript index.ts +const port = process.env.PORT || 8000; +app.listen(port, () => { + console.log(`Server running on port ${port}`); +}); +``` + +### Working Directory + +The `working_directory` property sets the base directory for the service. All other paths in the service configuration are resolved relative to this directory: + +```yaml title="Service with working directory" +services: + api: + subtype: # your choice, from target platform + working_directory: ./api + dev: + script: npm run dev # Runs from ./api directory + container: + docker: + dockerfile: Dockerfile # Resolves to ./api/Dockerfile + context: . # Resolves to ./api +``` + +**If not specified**, the project root (where `suga.yaml` is located) is used as the working directory. + +#### Monorepo Example + +Working directories are particularly useful in monorepo structures: + +```yaml title="Monorepo with multiple services" +services: + api: + subtype: # your choice, from target platform + working_directory: ./services/api + dev: + script: npm run dev + container: + docker: + dockerfile: Dockerfile + context: . + env: + SERVICE_NAME: api + + frontend: + subtype: # your choice, from target platform + working_directory: ./services/frontend + dev: + script: npm run dev + container: + docker: + dockerfile: Dockerfile + context: . + env: + SERVICE_NAME: frontend + + worker: + subtype: # your choice, from target platform + working_directory: ./services/worker + dev: + script: python main.py + container: + docker: + dockerfile: Dockerfile + context: . +``` + +Project structure: +``` +my-app/ +├── suga.yaml +└── services/ + ├── api/ + │ ├── Dockerfile + │ ├── package.json + │ └── src/ + ├── frontend/ + │ ├── Dockerfile + │ ├── package.json + │ └── src/ + └── worker/ + ├── Dockerfile + ├── requirements.txt + └── main.py +``` + +## Service Access Control + +Services can access other resources: + +```yaml +services: + api: + # Access granted through bucket configuration + +buckets: + uploads: + access: + api: [read, write, delete] + +databases: + main: + access: + api: [query] +``` + +This automatically generates IAM policies or service account permissions. + + + Learn more about access control patterns + + +## Accessing Resources from Services + +Services interact with resources like buckets using generated Suga client libraries. For databases, services receive connection strings via environment variables. + + + Learn how to access resources from your service code + + +## Learn More + + + + Grant resource access + + + + Test services locally + + + + Generated client libraries for resources + + + + Configure database access + + diff --git a/docs/develop/suga-client.mdx b/docs/develop/suga-client.mdx new file mode 100644 index 00000000..b54c455f --- /dev/null +++ b/docs/develop/suga-client.mdx @@ -0,0 +1,250 @@ +--- +title: "Suga Client Libraries" +description: "Generated client libraries for cloud-agnostic resource access" +--- + +Once you've defined resources in your `suga.yaml`, you need a way to interact with them from your application code. Suga provides **generated client libraries** that give you a cloud-agnostic interface to your resources. + +## Why Use Generated Clients? + +The Suga client generation approach offers several key advantages: + +- **Cloud Portability** - Same code works on AWS, GCP, or any platform +- **Local Development** - Enable `suga dev` with emulated cloud services +- **Type Safety** - IDE autocomplete and compile-time error checking +- **Simplified API** - Consistent interface across all cloud providers +- **Tailored Surface** - Only includes resources and permissions you've defined + +## What Resources Support Client Generation? + +Currently, Suga generates clients for: + +- **Buckets** - Object storage operations (read, write, delete) + +For other resources: +- **Databases** - Use standard PostgreSQL libraries with injected connection strings (see [Database Access](/develop/databases)) +- **Services** - Communicate through entrypoints or shared resources + +### Generated Client Libraries + +Generate type-safe client libraries using the `suga generate` command: + + + + ```bash + suga generate --node --node-out ./suga + ``` + + ```typescript + import { SugaClient } from './suga/client'; + import { Pool } from 'pg'; + + const suga = new SugaClient(); + + // Access bucket + await suga.uploads.write('file.txt', Buffer.from('Hello!')); + const data = await suga.uploads.read('file.txt'); + + // Access database (using injected connection string) + const pool = new Pool({ connectionString: process.env.DATABASE_URL }); + const result = await pool.query('SELECT * FROM users WHERE active = $1', [true]); + ``` + + + + ```bash + suga generate --python --python-out ./suga + ``` + + ```python + from suga.client import SugaClient + import psycopg2 + import os + + suga = SugaClient() + + # Access bucket + suga.uploads.write('file.txt', b'Hello!') + data = suga.uploads.read('file.txt') + + # Access database (using injected connection string) + conn = psycopg2.connect(os.environ['DATABASE_URL']) + cursor = conn.cursor() + cursor.execute('SELECT * FROM users WHERE active = %s', [True]) + users = cursor.fetchall() + ``` + + + + ```bash + suga generate --go --go-out ./suga --go-package-name suga + ``` + + ```go + import ( + "myapp/suga" + "os" + "github.com/jackc/pgx/v5/pgxpool" + ) + + client, _ := suga.NewClient() + + // Access bucket + client.Uploads.Write("file.txt", []byte("Hello!")) + data, _ := client.Uploads.Read("file.txt") + + // Access database (using injected connection string) + pool, _ := pgxpool.New(context.Background(), os.Getenv("DATABASE_URL")) + rows, _ := pool.Query(context.Background(), "SELECT * FROM users WHERE active = $1", true) + ``` + + + +The generated client automatically includes only the resources and permissions defined in your `suga.yaml`, providing a tailored API surface for your application. + +### Cloud-Agnostic Portability + +The Suga client maximizes portability by abstracting away cloud provider differences. When you use the client to interact with resources, **the same code works regardless of where your application is deployed**: + +```typescript title="Write once, run anywhere" +// This code works identically on: +// - Local development (file system emulation) +// - AWS deployment (S3) +// - GCP deployment (Cloud Storage) +// - Any custom platform + +await suga.uploads.write('user-profile.jpg', imageData); +``` + +**Without Suga**, you'd need different code for each cloud provider: + +```typescript title="Cloud-specific code (without Suga)" +// AWS +import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'; +const s3 = new S3Client({ region: 'us-east-1' }); +await s3.send(new PutObjectCommand({ Bucket: 'my-bucket', Key: 'file.txt', Body: data })); + +// GCP +import { Storage } from '@google-cloud/storage'; +const storage = new Storage(); +await storage.bucket('my-bucket').file('file.txt').save(data); +``` + +By reducing reliance on cloud-specific SDKs, Suga enables: +- **True multi-cloud deployment** - Switch providers without changing application code +- **Simplified codebase** - No conditional logic for different cloud providers +- **Easier testing** - Mock resources uniformly across environments +- **Future-proofing** - Platform changes don't require application code updates + +### Local Development with `suga dev` + +The generated client unlocks powerful local development capabilities. When you run `suga dev`, Suga automatically substitutes real cloud services with local emulations: + +```bash +suga dev +``` + +``` +suga dev + + ⚡ Suga Pre-release (adb9021) + - App: my_app + - Addr: :50051 + +Databases + +✓ Starting [database] postgresql://localhost:5433/database + +Services + +✓ Starting [worker] +✓ Starting [api] + +Entrypoints + +✓ Starting [ingress] http://localhost:3002 + +Use Ctrl-C to exit +``` + +**Your application code doesn't change** - the same client calls work locally: + +```typescript +// Works both locally and in production +await suga.uploads.write('file.txt', data); +// Local: writes to .suga/buckets/uploads/ +// AWS: writes to S3 +// GCP: writes to Cloud Storage +``` + +This seamless transition between local and cloud environments means: +- **No cloud account needed** for development +- **Zero cloud costs** during development +- **Fast iteration** - test changes instantly without deployment +- **Offline development** - work anywhere, no internet required +- **Consistent behavior** - same resource interactions locally and in production + +### How It Works + +The Suga client uses runtime adapters provided by your target platform's plugins: + +1. **In Production:** + ``` + Application → Suga Client → Platform Runtime Adapter → Cloud Provider SDK → Cloud Service + ``` + Example: `suga.uploads.write()` → S3 Adapter → AWS SDK → S3 + +2. **During `suga dev`:** + ``` + Application → Suga Client → Local Emulation Adapter → File System + ``` + Example: `suga.uploads.write()` → Local Adapter → `.suga/buckets/uploads/` + +The application code remains identical - only the underlying adapter changes based on the environment. + +### Type Safety and Auto-Completion + +Generated clients provide full type safety and IDE auto-completion: + +```typescript +const suga = new SugaClient(); + +// IDE knows about all your resources +suga.uploads. // ← Auto-complete shows: write, read, delete +suga.unknownBucket. // ← Compile error: doesn't exist in suga.yaml +``` + +This catches errors at development time rather than runtime, and makes exploring the API easier. + +### When to Use the Generated Client + +**Use the generated Suga client when:** +- You want cloud-agnostic code +- You need local development with `suga dev` +- You're building a multi-cloud application +- You want simplified resource access + +**Use native cloud SDKs directly when:** +- You need cloud-specific features not exposed by Suga +- You have deep integration requirements with a specific provider +- You're gradually migrating an existing application + +You can mix both approaches - use Suga clients for common operations and native SDKs for specialized needs. + + + + Complete API documentation + + + + Learn about local development workflow + + + + CLI reference for suga generate + + + + Configure resource permissions + + \ No newline at end of file diff --git a/docs/docs.json b/docs/docs.json index dbfba55e..ae338f53 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -19,30 +19,59 @@ "groups": [ { "group": "Getting Started", - "pages": ["introduction", "installation", "quickstart"] + "pages": ["introduction", "why-suga", "installation", "quickstart"] }, { "group": "Core Concepts", - "pages": ["projects", "platforms"] + "pages": [ + "core/overview", + "core/projects", + "core/platforms", + "core/plugins", + "core/infrastructure-generation", + "core/local-development" + ] + }, + { + "group": "Develop", + "pages": [ + "develop/overview", + "develop/services", + "develop/entrypoints", + "develop/buckets", + "develop/databases", + "develop/suga-client", + "develop/access-control" + ] + }, + { + "group": "Deploy", + "pages": [ + "deploy/overview", + "deploy/aws", + "deploy/gcp", + "deploy/azure", + "deploy/terraform-configuration" + ] }, { "group": "Guides", "pages": [ - "guides", + "guides/overview", "guides/add-suga", + "guides/static-website-hosting", "guides/personal-access-tokens", "guides/cicd-authentication", "guides/mcp-integration", "guides/build-platform", "guides/plugin-development", "guides/database-migration", - "guides/terraform-backend-config", - "guides/aws/environment-management" + "guides/terraform-backend-config" ] }, { "group": "Resources", - "pages": ["registry"] + "pages": ["registry", "faq", "support"] } ] }, @@ -88,17 +117,32 @@ { "group": "Python", "icon": "python", - "pages": ["sdks/python", "sdks/python/storage"] + "pages": [ + "sdks/python", + "sdks/python/client", + "sdks/python/storage", + "sdks/python/databases" + ] }, { "group": "Node.js", "icon": "node-js", - "pages": ["sdks/node", "sdks/node/storage"] + "pages": [ + "sdks/node", + "sdks/node/client", + "sdks/node/storage", + "sdks/node/databases" + ] }, { "group": "Go", "icon": "golang", - "pages": ["sdks/go", "sdks/go/storage"] + "pages": [ + "sdks/go", + "sdks/go/client", + "sdks/go/storage", + "sdks/go/databases" + ] } ] } @@ -160,5 +204,15 @@ "posthog": { "apiKey": "phc_XwujEojDf0Qq5EeBqOTo0Xf9ZAi7NZZIrIvvLGr8sZ6" } - } + }, + "redirects": [ + { + "source": "/projects", + "destination": "/core/projects" + }, + { + "source": "/platforms", + "destination": "/core/platforms" + } + ] } diff --git a/docs/faq.mdx b/docs/faq.mdx new file mode 100644 index 00000000..963f2cab --- /dev/null +++ b/docs/faq.mdx @@ -0,0 +1,220 @@ +--- +title: "Frequently Asked Questions" +description: "Common questions about Suga" +--- + +## General + +### What is Suga? + +Suga is a cloud development platform that combines visual infrastructure design with platform-driven governance. It generates production-ready Terraform from high-level application specifications, enabling developers to deploy instantly while platform teams maintain complete control. + +### How is Suga different from other tools? + +See our [Why Suga?](/why-suga) page for detailed comparisons with PaaS platforms, raw Terraform/Pulumi, and serverless frameworks. + +### Is Suga open source? + +The Suga CLI, official platforms and plugins are open-source, including the Terraform generation code (engines). + +You can access, review and contribute on [GitHub](https://github.com/nitrictech/suga) + +### What cloud providers does Suga support? + +- **AWS** - Lambda, Fargate, S3, CloudFront (full support) +- **GCP** - Cloud Run, Cloud Storage, Cloud CDN (full support) +- **Azure** - Coming soon + +Custom platforms can target any cloud provider, using standard Terraform Modules. + +## Getting Started + +### Do I need cloud provider experience? + +Basic familiarity helps, but Suga abstracts much of the complexity. You can deploy without being a cloud expert. + +### Can I use Suga with my existing application? + +Yes! See the [Add Suga to Existing Apps](/guides/add-suga) guide. + +### Do I need to learn Terraform? + +No, but understanding Terraform basics can help when customizing deployments. Suga generates all Terraform for you. + +### Can I develop without cloud access? + +Yes! `suga dev` provides local emulation of cloud services with no cloud account or internet connection needed. + +## Technical + +### What languages does Suga support? + +Services can be written in any language that runs in a container (Node.js, Python, Go, Java, Ruby, etc.). + +The optional SDK client generation currently supports: +- Node.js/TypeScript +- Python +- Go + +### Can I use custom cloud configurations? + +Yes, you can: +1. Override platform variables +2. Add custom Terraform resources +3. Create custom platforms +4. Build custom plugins + +### How does Suga handle state? + +Suga uses standard Terraform state management. Use remote backends (S3, GCS, Terraform Cloud) for team collaboration. + +### Can I migrate away from Suga? + +Yes. The generated Terraform is standard and can be maintained independently if you decide to stop using Suga. + +### Does Suga support Kubernetes? + +Not yet, but Kubernetes platform support is planned. + +## Deployment + +### How much does deployment cost? + +Suga is free to get started, you can see complete pricing details on the [pricing page](https://addsuga.com/pricing) + +There is no Suga markup on cloud costs. + +### How long does deployment take? + +First deployment: 5-15 minutes (Terraform provisioning cloud resources) +Code updates: 1-5 minutes (depends on service type and cloud provider) + +### Can I deploy to multiple environments? + +Yes! Use Terraform workspaces or separate state files: + +```bash +terraform workspace new prod +terraform workspace new staging +terraform workspace new dev +``` + +### How do I roll back a deployment? + +Revert your code changes, rebuild with `suga build`, and `terraform apply`. Terraform will update to the previous configuration. + +### What happens if deployment fails? + +Terraform will show the error and leave your infrastructure in a consistent state. Fix the issue and run `terraform apply` again. + +## Development + +### Can I use my own frameworks? + +Yes! Suga works with Express, FastAPI, Django, Go HTTP, and any other framework that runs in a container. + +### How do I debug services locally? + +Use your language's standard debugger with `suga dev`. See the [Local Development](/core/local-development) guide. + +### Can services communicate with each other? + +Currently, services communicate through shared databases or buckets. Direct service-to-service communication is coming soon. + +### What if I need a resource type that doesn't exist? + +You can: +1. Add custom Terraform resources to your stack +2. Create a custom plugin for the resource +3. Request the feature for official platforms +4. Extend Suga through [open source contributions](https://github.com/nitrictech/suga) + +## Platform & Plugin Development + +### Who should create platforms? + +Platform teams, DevOps/SRE teams, or anyone wanting to standardize infrastructure across an organization. + +### Can I customize official platforms? + +You can't modify official platforms directly, but you can: +1. Fork and customize them as your own private or public platforms +2. Override configurations through Terraform variables +3. Add custom resources alongside generated ones + +### How do I share platforms with my team? + +Publish platforms to your organization's Suga account. Team members can then target your custom platforms. + +### Do plugins require special permissions? + +Plugins are Terraform modules and run with your cloud provider credentials during `terraform apply`. They have the same permissions as any Terraform code. + +## Pricing & Licensing + +### Is Suga free? + +Suga is free to sign-up and has paid offering for teams and enterprise, see the [pricing page](https://addsuga.com/pricing) for complete details. + +You only pay your cloud provider for infrastructure resources. + +### Do I need a Suga account? + +Yes, a Suga account is required. Sign up at [addsuga.com](https://app.addsuga.com/signup). + +In the future, some features may work without an account. + +### Can I use Suga for commercial projects? + +Yes, Suga is designed for production use in commercial applications. + +## Support + +### How do I get help? + +- **Documentation** - [docs.addsuga.com](https://docs.addsuga.com) +- **Email Support** - [support@addsuga.com](mailto:support@addsuga.com) +- **GitHub Issues** - [github.com/nitrictech/suga](https://github.com/nitrictech/suga) + +### How do I report bugs? + +Report bugs via: +- GitHub Issues for public bugs +- Email [support@addsuga.com](mailto:support@addsuga.com) for security issues + +### Can I request features? + +Yes! Submit feature requests through GitHub Issues or email. + +### Do you offer paid support? + +Enterprise support options are available. Contact [sales@addsuga.com](mailto:sales@addsuga.com). + +## Security + +### How secure is Suga? + +- Suga generates standard Terraform with least-privilege IAM policies +- Your code and infrastructure remain in your cloud account +- Suga CLI only communicates with Suga platform services for authentication and platform/plugin retrieval +- No application code is sent to Suga servers + +### Where is my data stored? + +- Application data: In your cloud provider account +- Terraform state: Where you configure it (local, S3, GCS, Terraform Cloud) +- Suga platform: Stores only account info and platform/plugin definitions + +### Does Suga have access to my cloud resources? + +No. Suga generates Terraform that you deploy with your own cloud credentials. Suga has no access to your deployed resources. + +### How do I handle secrets? + +Currently, use your cloud provider's secrets manager and reference via environment variables. + +## Still Have Questions? + + + Reach out to our team at support@addsuga.com + diff --git a/docs/guides/build-platform.mdx b/docs/guides/build-platform.mdx index 4b93a51b..7c225572 100644 --- a/docs/guides/build-platform.mdx +++ b/docs/guides/build-platform.mdx @@ -3,14 +3,14 @@ title: "Platform Development Guide" description: "Learn to build platforms with Suga through a hands-on example." --- -Platforms can start simple and evolve as your needs grow. This guide walks through building a single platform that supports multiple deployment strategies using standard [plugin](/platforms#plugins) libraries provided by the Suga team, which include plugins for Lambda, Fargate, CloudFront, S3, VPC, and Neon databases. +Platforms can start simple and evolve as your needs grow. This guide walks through building a single platform that supports multiple deployment strategies using standard [plugin](/core/platforms#plugins) libraries provided by the Suga team, which include plugins for Lambda, Fargate, CloudFront, S3, VPC, and Neon databases. **Phase 1: Serverless Platform** - Build a minimal platform with Lambda functions, databases, storage, and CDN. **Phase 2: Add Stateful Services** - Extend the same platform to support containers running on Amazon ECS Fargate, alongside Lambda by adding VPC infrastructure, load balancers, and security groups. - **New to Suga platforms?** See the [Platforms Overview](/platforms) to understand how platforms work and why they're useful. Don't want to manage platforms? Use Suga's default platforms and jump to the [Quickstart](/quickstart). + **New to Suga platforms?** See the [Platforms Overview](/core/platforms) to understand how platforms work and why they're useful. Don't want to manage platforms? Use Suga's default platforms and jump to the [Quickstart](/quickstart). ## Phase 1: Build Serverless Platform @@ -43,8 +43,8 @@ Fill out the platform details and click **"Create Platform"**: The platform editor has two sections: -- **[Foundations](/platforms#variables)** - Common infrastructure shared by other resources (VPCs, load balancers) and common variables for platform configuration -- **[Resource Blueprints](/platforms#resource-blueprints)** - Templates that define how to provision application specific resources, such as services, databases, buckets, and entrypoints +- **[Core Concepts](/core/platforms#variables)** - Common infrastructure shared by other resources (VPCs, load balancers) and common variables for platform configuration +- **[Resource Blueprints](/core/platforms#resource-blueprints)** - Templates that define how to provision application specific resources, such as services, databases, buckets, and entrypoints ![Edit Platform Dialog](/images/build-platform/edit-platform.png) @@ -102,7 +102,7 @@ This blueprint maps an application's databases to Neon PostgreSQL with automatic Expand **Database Blueprints** in Resource Blueprints. -Add platform variable in **Foundations** to specify which Neon project to create databases in: +Add platform variable in **Core Concepts** to specify which Neon project to create databases in: ```yaml neon_project_id: type: string @@ -129,7 +129,7 @@ branch_id: ${self.neon_branch_id} Suga uses three types of references in platform configurations: - - `${var.name}` - References platform variables from Foundations + - `${var.name}` - References platform variables from Core Concepts - `${self.name}` - References resource-specific variables defined in the same resource blueprint - `${infra.name.output}` - References outputs from infrastructure components (you'll see this in Phase 2) @@ -148,7 +148,7 @@ Click "Commit Revision" in the platform editor, add a descriptive commit message ### Test with an Application -Create an [application](/projects) from the project editor and design your application architecture using the platform you just created. +Create an [application](/core/projects) from the project editor and design your application architecture using the platform you just created. Not familiar with building applications with Suga? Start with the [Quickstart guide](/quickstart). @@ -172,7 +172,7 @@ This architecture shows CloudFront routing to an Application Load Balancer, whic To extend the platform with stateful services, the platform will need the following infrastructure and blueprints: -**Shared Infrastructure (Foundations)**: +**Shared Infrastructure (Core Concepts)**: - **VPC** - Private network for Fargate containers - **Security Group Rules** - Firewall rules for container traffic - **Load Balancer** - Internal ALB for routing to Fargate containers @@ -188,7 +188,7 @@ To extend the platform with stateful services, the platform will need the follow This shared infrastructure configures the VPC network foundation with isolated subnets, NAT gateways, and routing for stateful containers. Unlike serverless Lambda functions, Fargate containers require a private network to run securely. -In the **Foundations** section, expand **Infrastructure**. +In the **Core Concepts** section, expand **Infrastructure**. Add the `vpc` plugin and apply the following configuration: ```yaml @@ -214,7 +214,7 @@ single_nat_gateway: ${self.single_nat_gateway} These platform variables configure the network ports for container communication. The `container_port` defines where containers listen for traffic, while `lb_listener_port` defines where the load balancer accepts incoming requests. -Add platform variables in **Foundations**: +Add platform variables in **Core Concepts**: ```yaml container_port: @@ -234,7 +234,7 @@ lb_listener_port: This shared infrastructure configures firewall rules for container network traffic: outbound internet access, health check access, and CDN-only ingress. These rules ensure containers can communicate with external services while blocking unauthorized access. -In the **Foundations** section, expand **Infrastructure**. +In the **Core Concepts** section, expand **Infrastructure**. **Outbound Internet Access** @@ -308,7 +308,7 @@ security_group_ids: ["${infra.aws_vpc.default_security_group_id}"] This shared infrastructure configures an internal Application Load Balancer to route traffic and perform health checks for containers. The load balancer distributes incoming requests across container instances and removes unhealthy containers from rotation. -In the **Foundations** section, expand **Infrastructure**. +In the **Core Concepts** section, expand **Infrastructure**. Add the `loadbalancer` plugin and apply the following configuration: @@ -388,7 +388,7 @@ This enables different services within the same application to use different arc If you see errors about missing infrastructure references: - Verify plugin names match exactly (e.g., `${infra.aws_vpc}` requires a plugin named `aws_vpc`) - Check that dependencies are declared before using outputs -- Ensure infrastructure components are in the Foundations section, not Resource Blueprints +- Ensure infrastructure components are in the Core Concepts section, not Resource Blueprints **Platform won't commit** @@ -406,7 +406,7 @@ If building an application produces Terraform errors: ## Next Steps -- **Test with a real application**: Create an [application](/projects) using this platform, [build the Terraform](/cli/build), and deploy to AWS to verify everything works end-to-end +- **Test with a real application**: Create an [application](/core/projects) using this platform, [build the Terraform](/cli/build), and deploy to AWS to verify everything works end-to-end - **Share with your team**: Make the platform available to your team so they can start building applications - **Create environment variants**: Duplicate your platform with environment-specific variables (e.g., smaller instances for dev, larger for prod) diff --git a/docs/guides.mdx b/docs/guides/overview.mdx similarity index 98% rename from docs/guides.mdx rename to docs/guides/overview.mdx index aa4fb9b8..02aa8553 100644 --- a/docs/guides.mdx +++ b/docs/guides/overview.mdx @@ -1,5 +1,6 @@ --- title: "Guides Overview" +sidebarTitle: "Overview" description: "Learn how to leverage Suga for common infrastructure patterns and workflows" --- diff --git a/docs/guides/plugin-development.mdx b/docs/guides/plugin-development.mdx index c8ca05c0..9c1edc81 100644 --- a/docs/guides/plugin-development.mdx +++ b/docs/guides/plugin-development.mdx @@ -504,9 +504,11 @@ go mod init github.com/myorg/my-plugins # Create your first plugin mkdir lambda cd lambda +``` + +Create the plugin manifest: -# Create manifest -cat > manifest.yaml << 'EOF' +```yaml title="lambda/manifest.yaml" name: lambda type: service description: "My custom Lambda implementation" @@ -527,14 +529,16 @@ inputs: description: "Memory allocation in MB" outputs: {} -EOF +``` + +Create the Terraform module directory and files: -# Create Terraform module +```bash mkdir module cd module +``` -# Create basic Terraform files -cat > variables.tf << 'EOF' +```hcl title="module/variables.tf" variable "name" { type = string description = "Function name" @@ -551,22 +555,21 @@ variable "memory" { description = "Memory in MB" default = 1024 } -EOF +``` -cat > main.tf << 'EOF' +```hcl title="module/main.tf" resource "aws_lambda_function" "this" { function_name = var.name timeout = var.timeout memory_size = var.memory # ... add your custom Lambda configuration } -EOF +``` -cat > outputs.tf << 'EOF' +```hcl title="module/outputs.tf" output "function_arn" { value = aws_lambda_function.this.arn } -EOF ``` ### Step 2: Start the Plugin Development Server @@ -810,7 +813,7 @@ This is particularly valuable when writing runtime adapters if you're more famil - [Platform Development Guide](/guides/build-platform) - Learn how platforms compose plugins - [Suga MCP Integration](/guides/mcp-integration) - Use AI agents to help build plugins -- [Platforms Overview](/platforms) - Understand how plugins fit into the architecture +- [Platforms Overview](/core/platforms) - Understand how plugins fit into the architecture - [Suga CLI Reference](/cli) - Complete CLI documentation diff --git a/docs/guides/static-website-hosting.mdx b/docs/guides/static-website-hosting.mdx new file mode 100644 index 00000000..ee2f1dc8 --- /dev/null +++ b/docs/guides/static-website-hosting.mdx @@ -0,0 +1,342 @@ +--- +title: "Static Website Hosting" +description: "Deploy static websites and single-page applications with Suga" +--- + +Host static websites and single-page applications (React, Vue, Angular, Svelte) with Suga using buckets and entrypoints for CDN-backed delivery. + +## How It Works + +Static website hosting in Suga combines two resources: + +1. **Bucket** - Stores your static files (HTML, CSS, JavaScript, images) +2. **Entrypoint** - Routes traffic to the bucket through a CDN + +```yaml title="Basic static site" +buckets: + frontend: + content_path: ./build # Your build output directory + +entrypoints: + web: + routes: + /: + name: frontend # Serve files from bucket +``` + +When you deploy: +1. Files from `./build` are uploaded to the bucket +2. The entrypoint (CDN) serves files from the bucket +3. Users access your site via HTTPS with automatic SSL + +## Single Page Applications (SPAs) + +Deploy React, Vue, Angular, or Svelte applications: + +```yaml title="suga.yaml" +target: suga/aws@1 +name: my-app + +buckets: + frontend: + content_path: ./dist # Vite/Vue/Angular build output + +entrypoints: + web: + routes: + /: + name: frontend +``` + +**Build your app, then deploy:** + +```bash +# Build your frontend +npm run build + +# Generate infrastructure +suga build + +# Deploy +cd terraform/stacks/my-app +terraform init +terraform apply +``` + +Your SPA is now live with CDN delivery and HTTPS! + +## Static Site + API + +Most applications need both frontend and backend. Route different paths to different destinations: + +```yaml title="Frontend + Backend" +services: + api: + dev: + script: npm run dev + container: + docker: + dockerfile: Dockerfile + context: . + +buckets: + frontend: + content_path: ./frontend/build + +entrypoints: + web: + routes: + /api/: + name: api # API requests go to service + /: + name: frontend # Everything else goes to static files +``` + +**How routing works:** +- `https://yoursite.com/` → Static files from bucket +- `https://yoursite.com/about` → Static files from bucket +- `https://yoursite.com/api/users` → API service +- `https://yoursite.com/api/products` → API service + +## Multi-Page Applications + +Deploy traditional multi-page websites: + +```yaml +buckets: + website: + content_path: ./public + +entrypoints: + web: + routes: + /: + name: website +``` + +**Directory structure:** + +``` +public/ +├── index.html +├── about.html +├── contact.html +├── css/ +│ └── style.css +├── js/ +│ └── script.js +└── images/ + └── logo.png +``` + +All files are uploaded to the bucket at deploy time and served via CDN. + +## Build Process Integration + +Integrate with your existing build tools: + +### React (Create React App / Vite) + +```yaml +buckets: + frontend: + content_path: ./build # CRA output + # OR + content_path: ./dist # Vite output +``` + +```bash +npm run build +suga build +cd terraform/stacks/my-app && terraform apply +``` + +### Vue.js + +```yaml +buckets: + frontend: + content_path: ./dist +``` + +```bash +npm run build +suga build +cd terraform/stacks/my-app && terraform apply +``` + +### Angular + +```yaml +buckets: + frontend: + content_path: ./dist/my-app # Angular outputs to dist/project-name +``` + +```bash +ng build --configuration production +suga build +cd terraform/stacks/my-app && terraform apply +``` + +### Next.js (Static Export) + +```yaml +buckets: + frontend: + content_path: ./out +``` + +```json title="package.json" +{ + "scripts": { + "build": "next build && next export" + } +} +``` + +```bash +npm run build +suga build +cd terraform/stacks/my-app && terraform apply +``` + +### Svelte/SvelteKit + +```yaml +buckets: + frontend: + content_path: ./build +``` + +```bash +npm run build +suga build +cd terraform/stacks/my-app && terraform apply +``` + +## Custom Domains + +Most platforms support custom domains through Terraform variables: + + + + After running `suga build`, configure your domain: + + ```hcl title="terraform/stacks/my-app/terraform.tfvars" + custom_domain = "www.example.com" + ``` + + Then apply: + + ```bash + terraform apply + ``` + + + AWS requires ACM certificates in `us-east-1` for CloudFront. Create your certificate in ACM first. + + + + + The GCP platform requires that you have a Cloud DNS zone already created. After it's created and you've run `suga build`, you can add the configuration: + + ```hcl title="terraform/stacks/my-app/terraform.tfvars" + dns_zone_name = "name_of_your_zone" + domain_name = "www.example.com" + ``` + + Then apply: + + ```bash + terraform apply + ``` + + + +## Environment Variables in Frontend + +Frontend applications often need runtime configuration (API URLs, feature flags, etc.): + +### Build-time Variables + +```yaml title="suga.yaml" +services: + api: + dev: + script: npm run dev + +buckets: + frontend: + content_path: ./build + +entrypoints: + web: + routes: + /api/: + name: api + /: + name: frontend +``` + +```javascript title=".env.production" +REACT_APP_API_URL=/api +VITE_API_URL=/api +``` + +Build and deploy: + +```bash +npm run build # Variables baked into bundle +suga build +cd terraform/stacks/my-app && terraform apply +``` + +## Local Development + +During `suga dev`: + +```bash +suga dev +``` + +- Buckets are emulated in `.suga/buckets/` +- Static files are served from the local filesystem +- Changes to files in `content_path` require rebuild and re-upload in production + +**Development workflow:** + +```bash +# Terminal 1: Run Suga dev server +suga dev + +# Terminal 2: Run frontend dev server separately +cd frontend +npm run dev # Usually runs on :3000 or :5173 +``` + +During development, use your framework's dev server (with hot reload) rather than the production build. + + + Learn more about local development workflow + + +## Learn More + + + + Object storage configuration + + + + HTTP routing and CDN + + + + Deployment workflow + + + + Automate deployments + + diff --git a/docs/images/develop/access-control/service-to-bucket-access-control.png b/docs/images/develop/access-control/service-to-bucket-access-control.png new file mode 100644 index 00000000..183f49f0 Binary files /dev/null and b/docs/images/develop/access-control/service-to-bucket-access-control.png differ diff --git a/docs/images/develop/app-diagram-example.png b/docs/images/develop/app-diagram-example.png new file mode 100644 index 00000000..e46ef838 Binary files /dev/null and b/docs/images/develop/app-diagram-example.png differ diff --git a/docs/installation.mdx b/docs/installation.mdx index 2f125560..957a0b72 100644 --- a/docs/installation.mdx +++ b/docs/installation.mdx @@ -10,7 +10,7 @@ import { OSTabs } from '/snippets/os-tabs.jsx'; The Suga CLI is all you need to get started with Suga. It provides everything required to build, test, and deploy cloud-native applications with automatic infrastructure generation. - **Early Access:** During the early access period, a Suga account is required, you can request an invite at https://addsuga.com. You'll need to run `suga login` after installation to authenticate. We plan to make certain functionality available without an account in future releases. + A Suga account is required, sign-up for a free account at https://app.addsuga.com/signup. ## Quick Install diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx index f0dffcc6..1f0e8cab 100644 --- a/docs/quickstart.mdx +++ b/docs/quickstart.mdx @@ -6,9 +6,7 @@ description: "Get started with Suga in minutes - build, test, and deploy cloud a The Suga CLI provides everything you need to build cloud applications with automatic infrastructure generation for many cloud providers. - **Prerequisites:** This guide assumes you have the Suga CLI installed. If you - need to install it, see the [Installation Guide](/installation) for - platform-specific instructions. + **Prerequisites:** This guide assumes you have the Suga CLI installed. See the [Installation Guide](/installation) for instructions. ## Sign In to Suga @@ -19,9 +17,9 @@ Sign in to the Suga platform: suga login ``` - - If you don't have a Suga account yet you can request access at [addsuga.com](https://addsuga.com) - + + A Suga account is required, sign-up for a free account at https://app.addsuga.com/signup. + You'll see a confirmation: ```bash @@ -30,10 +28,6 @@ You'll see a confirmation: ✓ Logged in as User ``` - - During early access authentication is required to access all Suga platform features. In the future, certain features may be made available without signing in. - - ## Create Your Project Create a new project from a template: @@ -375,8 +369,8 @@ If you make changes to your application in the future, you can re-run `suga buil Now that you know how to use Suga to develop and deploy cloud applications, consider some of these docs to continue learning about Suga: -- [Projects overview](/projects) -- [Platforms overview](/platforms) +- [Projects overview](/core/projects) +- [Platforms overview](/core/platforms) - [Add Suga to an existing application](/guides/add-suga) diff --git a/docs/sdks/go/client.mdx b/docs/sdks/go/client.mdx new file mode 100644 index 00000000..f063e121 --- /dev/null +++ b/docs/sdks/go/client.mdx @@ -0,0 +1,56 @@ +--- +title: "Suga Client (Go)" +description: "Suga client initialization and configuration for Go" +--- + +Initialize and configure the Suga client in Go applications. + +## Installation + +Generated client is part of your project after running: + +```bash +suga generate --go --go-out ./suga --go-package-name suga +``` + +## Basic Usage + +```go +package main + +import ( + "myapp/suga" + "log" +) + +func main() { + // Initialize client + client, err := suga.NewClient() + if err != nil { + log.Fatal(err) + } + + // Access resources + err = client.Uploads.Write("file.txt", []byte("data")) + if err != nil { + log.Fatal(err) + } + + data, err := client.Uploads.Read("file.txt") + if err != nil { + log.Fatal(err) + } +} +``` + +## Learn More + + + + Bucket operations + + + + Database operations + + diff --git a/docs/sdks/go/databases.mdx b/docs/sdks/go/databases.mdx new file mode 100644 index 00000000..eb641dba --- /dev/null +++ b/docs/sdks/go/databases.mdx @@ -0,0 +1,229 @@ +--- +title: "Databases" +description: "Accessing PostgreSQL databases from Go applications" +--- + +Access PostgreSQL databases from Go applications using standard PostgreSQL libraries with automatically injected connection strings. + +## Connection String Injection + +Suga automatically injects database connection strings as environment variables for services with database access: + +```yaml title="suga.yaml" +databases: + main: + subtype: neon + access: + api: [query] + env_var_key: DATABASE_URL +``` + +The `api` service automatically receives `DATABASE_URL` containing the full connection string. + +## Using pgx + +```bash +go get github.com/jackc/pgx/v5/pgxpool +``` + +```go +package main + +import ( + "context" + "fmt" + "os" + "github.com/jackc/pgx/v5/pgxpool" +) + +func main() { + // Connection string automatically injected by Suga + pool, err := pgxpool.New(context.Background(), os.Getenv("DATABASE_URL")) + if err != nil { + panic(err) + } + defer pool.Close() + + // Query with parameters + rows, err := pool.Query(context.Background(), + "SELECT * FROM users WHERE active = $1", true) + if err != nil { + panic(err) + } + defer rows.Close() + + // Insert data + _, err = pool.Exec(context.Background(), + "INSERT INTO users (name, email) VALUES ($1, $2)", + "Alice", "alice@example.com") + + // Update data + _, err = pool.Exec(context.Background(), + "UPDATE users SET name = $1 WHERE id = $2", + "Bob", 1) + + // Delete data + _, err = pool.Exec(context.Background(), + "DELETE FROM users WHERE id = $1", 1) +} +``` + +## Using GORM + +```bash +go get gorm.io/gorm +go get gorm.io/driver/postgres +``` + +```go +package main + +import ( + "os" + "gorm.io/driver/postgres" + "gorm.io/gorm" +) + +type User struct { + ID uint + Name string + Email string `gorm:"unique"` + Active bool `gorm:"default:true"` +} + +func main() { + // Connection string automatically injected by Suga + db, err := gorm.Open(postgres.Open(os.Getenv("DATABASE_URL")), &gorm.Config{}) + if err != nil { + panic(err) + } + + // Query + var users []User + db.Where("active = ?", true).Find(&users) + + // Insert + db.Create(&User{ + Name: "Alice", + Email: "alice@example.com", + }) + + // Update + db.Model(&User{}).Where("id = ?", 1).Update("name", "Bob") + + // Delete + db.Delete(&User{}, 1) +} +``` + +## Using sqlx + +```bash +go get github.com/jmoiron/sqlx +go get github.com/lib/pq +``` + +```go +package main + +import ( + "os" + "github.com/jmoiron/sqlx" + _ "github.com/lib/pq" +) + +type User struct { + ID int `db:"id"` + Name string `db:"name"` + Email string `db:"email"` + Active bool `db:"active"` +} + +func main() { + // Connection string automatically injected by Suga + db, err := sqlx.Connect("postgres", os.Getenv("DATABASE_URL")) + if err != nil { + panic(err) + } + defer db.Close() + + // Query + users := []User{} + db.Select(&users, "SELECT * FROM users WHERE active = $1", true) + + // Insert + db.Exec("INSERT INTO users (name, email) VALUES ($1, $2)", + "Alice", "alice@example.com") + + // Update + db.Exec("UPDATE users SET name = $1 WHERE id = $2", "Bob", 1) +} +``` + +## Multiple Databases + +When accessing multiple databases, each has a unique environment variable: + +```yaml title="suga.yaml" +databases: + users: + access: + api: [query] + env_var_key: USERS_DATABASE_URL + + products: + access: + api: [query] + env_var_key: PRODUCTS_DATABASE_URL +``` + +```go +import ( + "context" + "os" + "github.com/jackc/pgx/v5/pgxpool" +) + +// Connect to different databases +usersPool, _ := pgxpool.New(context.Background(), os.Getenv("USERS_DATABASE_URL")) +productsPool, _ := pgxpool.New(context.Background(), os.Getenv("PRODUCTS_DATABASE_URL")) + +// Query different databases +usersRows, _ := usersPool.Query(context.Background(), "SELECT * FROM users") +productsRows, _ := productsPool.Query(context.Background(), "SELECT * FROM products") +``` + +## Connection Pooling + +pgxpool provides automatic connection pooling: + +```go +import ( + "context" + "os" + "github.com/jackc/pgx/v5/pgxpool" +) + +// Create pool with custom configuration +config, _ := pgxpool.ParseConfig(os.Getenv("DATABASE_URL")) +config.MaxConns = 20 +config.MinConns = 5 + +pool, _ := pgxpool.NewWithConfig(context.Background(), config) +defer pool.Close() + +// Pool automatically manages connections +rows, _ := pool.Query(context.Background(), "SELECT * FROM users") +``` + +## Learn More + + + + Learn about database setup + + + + Manage schema changes + + diff --git a/docs/sdks/node/client.mdx b/docs/sdks/node/client.mdx new file mode 100644 index 00000000..acade4cd --- /dev/null +++ b/docs/sdks/node/client.mdx @@ -0,0 +1,39 @@ +--- +title: "Suga Client (Node.js)" +description: "SugaClient initialization and configuration for Node.js/TypeScript" +--- + +Initialize and configure the Suga client in Node.js and TypeScript applications. + +## Installation + +Generated client is part of your project after running: + +```bash +suga generate --node --node-out ./suga +``` + +## Basic Usage + +```typescript +import { SugaClient } from './suga/client'; + +// Initialize client +const suga = new SugaClient(); + +// Access resources +await suga.uploads.write('file.txt', Buffer.from('data')); +const data = await suga.uploads.read('file.txt'); +``` + +## Learn More + + + + Bucket operations + + + + Database operations + + diff --git a/docs/sdks/node/databases.mdx b/docs/sdks/node/databases.mdx new file mode 100644 index 00000000..aad64d46 --- /dev/null +++ b/docs/sdks/node/databases.mdx @@ -0,0 +1,195 @@ +--- +title: "Databases" +description: "Accessing PostgreSQL databases from Node.js/TypeScript applications" +--- + +Access PostgreSQL databases from Node.js and TypeScript applications using standard PostgreSQL libraries with automatically injected connection strings. + +## Connection String Injection + +Suga automatically injects database connection strings as environment variables for services with database access: + +```yaml title="suga.yaml" +databases: + main: + subtype: neon + access: + api: [query] + env_var_key: DATABASE_URL +``` + +The `api` service automatically receives `DATABASE_URL` containing the full connection string. + +## Using pg (node-postgres) + +```bash +npm install pg +``` + +```typescript +import { Pool } from 'pg'; + +// Connection string automatically injected by Suga +const pool = new Pool({ + connectionString: process.env.DATABASE_URL +}); + +// Query with parameters +const result = await pool.query( + 'SELECT * FROM users WHERE active = $1', + [true] +); +const users = result.rows; + +// Insert data +await pool.query( + 'INSERT INTO users (name, email) VALUES ($1, $2)', + ['Alice', 'alice@example.com'] +); + +// Update data +await pool.query( + 'UPDATE users SET name = $1 WHERE id = $2', + ['Bob', 1] +); + +// Delete data +await pool.query('DELETE FROM users WHERE id = $1', [1]); +``` + +## Using Prisma ORM + +```bash +npm install prisma @prisma/client +``` + +```javascript title="prisma/schema.prisma" +datasource db { + provider = "postgresql" + url = env("DATABASE_URL") +} + +model User { + id Int @id @default(autoincrement()) + name String + email String @unique + active Boolean @default(true) +} +``` + +```typescript +import { PrismaClient } from '@prisma/client'; + +const prisma = new PrismaClient(); + +// Query +const users = await prisma.user.findMany({ + where: { active: true } +}); + +// Insert +await prisma.user.create({ + data: { name: 'Alice', email: 'alice@example.com' } +}); + +// Update +await prisma.user.update({ + where: { id: 1 }, + data: { name: 'Bob' } +}); +``` + +## Using TypeORM + +```bash +npm install typeorm reflect-metadata pg +``` + +```typescript +import { DataSource } from 'typeorm'; +import { User } from './entities/User'; + +const dataSource = new DataSource({ + type: 'postgres', + url: process.env.DATABASE_URL, + entities: [User], + synchronize: false, // Use migrations in production +}); + +await dataSource.initialize(); + +// Query +const users = await dataSource.getRepository(User).find({ + where: { active: true } +}); + +// Insert +await dataSource.getRepository(User).save({ + name: 'Alice', + email: 'alice@example.com' +}); +``` + +## Multiple Databases + +When accessing multiple databases, each has a unique environment variable: + +```yaml title="suga.yaml" +databases: + users: + access: + api: [query] + env_var_key: USERS_DATABASE_URL + + products: + access: + api: [query] + env_var_key: PRODUCTS_DATABASE_URL +``` + +```typescript +import { Pool } from 'pg'; + +const usersPool = new Pool({ + connectionString: process.env.USERS_DATABASE_URL +}); + +const productsPool = new Pool({ + connectionString: process.env.PRODUCTS_DATABASE_URL +}); + +// Query different databases +const users = await usersPool.query('SELECT * FROM users'); +const products = await productsPool.query('SELECT * FROM products'); +``` + +## Connection Pooling + +Always use connection pooling for better performance: + +```typescript +import { Pool } from 'pg'; + +// Create pool once +const pool = new Pool({ + connectionString: process.env.DATABASE_URL, + max: 20, // Maximum connections + idleTimeoutMillis: 30000, + connectionTimeoutMillis: 2000, +}); + +// Reuse the pool throughout your application +export default pool; +``` + +## Learn More + + + + Learn about database setup + + + + Manage schema changes + + diff --git a/docs/sdks/python.mdx b/docs/sdks/python.mdx index f74209db..19a44cb7 100644 --- a/docs/sdks/python.mdx +++ b/docs/sdks/python.mdx @@ -32,11 +32,11 @@ from suga_gen.client import SugaClient ```python # Initialize client -client = SugaClient() +suga = SugaClient() # Access your resources (names from your suga.yaml) -client.image.write("file.txt", b"data") -content = client.image.read("file.txt") +suga.image.write("file.txt", b"data") +content = suga.image.read("file.txt") ``` ## Available Resources diff --git a/docs/sdks/python/client.mdx b/docs/sdks/python/client.mdx new file mode 100644 index 00000000..96bf0074 --- /dev/null +++ b/docs/sdks/python/client.mdx @@ -0,0 +1,39 @@ +--- +title: "Suga Client (Python)" +description: "SugaClient initialization and configuration for Python" +--- + +Initialize and configure the Suga client in Python applications. + +## Installation + +Generated client is part of your project after running: + +```bash +suga generate --python --python-out ./suga_gen +``` + +## Basic Usage + +```python +from suga_gen.client import SugaClient + +# Initialize client +suga = SugaClient() + +# Access resources +suga.uploads.write('file.txt', b'data') +data = suga.uploads.read('file.txt') +``` + +## Learn More + + + + Bucket operations + + + + Database operations + + diff --git a/docs/sdks/python/databases.mdx b/docs/sdks/python/databases.mdx new file mode 100644 index 00000000..f46dc313 --- /dev/null +++ b/docs/sdks/python/databases.mdx @@ -0,0 +1,189 @@ +--- +title: "Databases" +description: "Accessing PostgreSQL databases from Python applications" +--- + +Access PostgreSQL databases from Python applications using standard PostgreSQL libraries with automatically injected connection strings. + +## Connection String Injection + +Suga automatically injects database connection strings as environment variables for services with database access: + +```yaml title="suga.yaml" +databases: + main: + subtype: neon + access: + api: [query] + env_var_key: DATABASE_URL +``` + +The `api` service automatically receives `DATABASE_URL` containing the full connection string. + +## Using psycopg2 + +```bash +pip install psycopg2-binary +``` + +```python +import psycopg2 +import os + +# Connection string automatically injected by Suga +conn = psycopg2.connect(os.environ['DATABASE_URL']) +cursor = conn.cursor() + +# Query with parameters +cursor.execute('SELECT * FROM users WHERE active = %s', [True]) +users = cursor.fetchall() + +# Insert data +cursor.execute( + 'INSERT INTO users (name, email) VALUES (%s, %s)', + ['Alice', 'alice@example.com'] +) +conn.commit() + +# Update data +cursor.execute( + 'UPDATE users SET name = %s WHERE id = %s', + ['Bob', 1] +) +conn.commit() + +# Delete data +cursor.execute('DELETE FROM users WHERE id = %s', [1]) +conn.commit() + +cursor.close() +conn.close() +``` + +## Using SQLAlchemy ORM + +```bash +pip install sqlalchemy psycopg2-binary +``` + +```python +from sqlalchemy import create_engine, Column, Integer, String, Boolean +from sqlalchemy.ext.declarative import declarative_base +from sqlalchemy.orm import sessionmaker +import os + +# Connection string automatically injected by Suga +engine = create_engine(os.environ['DATABASE_URL']) +Base = declarative_base() + +class User(Base): + __tablename__ = 'users' + id = Column(Integer, primary_key=True) + name = Column(String) + email = Column(String, unique=True) + active = Column(Boolean, default=True) + +Session = sessionmaker(bind=engine) +session = Session() + +# Query +users = session.query(User).filter(User.active == True).all() + +# Insert +user = User(name='Alice', email='alice@example.com') +session.add(user) +session.commit() + +# Update +user = session.query(User).filter(User.id == 1).first() +user.name = 'Bob' +session.commit() +``` + +## Using Django ORM + +```python title="settings.py" +import os +import dj_database_url + +DATABASES = { + 'default': dj_database_url.config( + default=os.environ['DATABASE_URL'], + conn_max_age=600 + ) +} +``` + +```bash +pip install dj-database-url psycopg2-binary +``` + +## Multiple Databases + +When accessing multiple databases, each has a unique environment variable: + +```yaml title="suga.yaml" +databases: + users: + access: + api: [query] + env_var_key: USERS_DATABASE_URL + + products: + access: + api: [query] + env_var_key: PRODUCTS_DATABASE_URL +``` + +```python +import psycopg2 +import os + +# Connect to different databases +users_conn = psycopg2.connect(os.environ['USERS_DATABASE_URL']) +products_conn = psycopg2.connect(os.environ['PRODUCTS_DATABASE_URL']) + +# Query different databases +users_cursor = users_conn.cursor() +users_cursor.execute('SELECT * FROM users') +users = users_cursor.fetchall() + +products_cursor = products_conn.cursor() +products_cursor.execute('SELECT * FROM products') +products = products_cursor.fetchall() +``` + +## Connection Pooling + +Use connection pooling for better performance: + +```python +from psycopg2 import pool +import os + +# Create connection pool +connection_pool = pool.SimpleConnectionPool( + 1, 20, # Min and max connections + os.environ['DATABASE_URL'] +) + +# Get connection from pool +conn = connection_pool.getconn() +cursor = conn.cursor() +cursor.execute('SELECT * FROM users') + +# Return connection to pool +connection_pool.putconn(conn) +``` + +## Learn More + + + + Learn about database setup + + + + Manage schema changes + + diff --git a/docs/sdks/python/storage.mdx b/docs/sdks/python/storage.mdx index 84324000..8fd62332 100644 --- a/docs/sdks/python/storage.mdx +++ b/docs/sdks/python/storage.mdx @@ -86,7 +86,7 @@ def list(prefix: str = "") -> List[str] #### Parameters - + Filter results to keys starting with this prefix @@ -148,7 +148,11 @@ def get_upload_url(key: str, options: Optional[PresignUrlOptions] = None) -> str The key/path of the file - + Configuration with expiry in seconds @@ -167,4 +171,4 @@ download_url = client.image.get_download_url("file.txt") # Upload URL with custom expiry (1 hour) upload_url = client.image.get_upload_url("file.txt", PresignUrlOptions(expiry=3600)) -``` \ No newline at end of file +``` diff --git a/docs/support.mdx b/docs/support.mdx new file mode 100644 index 00000000..8620c672 --- /dev/null +++ b/docs/support.mdx @@ -0,0 +1,89 @@ +--- +title: "Support" +description: "Get help with Suga" +--- + +Need help with Suga? We're here to assist you. + +## Documentation + +Start with our comprehensive documentation: + + + + Get started in minutes + + + + Understand core concepts + + + + Step-by-step tutorials + + + + Common questions answered + + + +## Contact Support + +### Email Support + +For general questions, technical issues, or account help: + +**[support@addsuga.com](mailto:support@addsuga.com)** + +We typically respond within 24 hours during business days. + +### GitHub Issues + +For bug reports, feature requests, and public discussions: + +**[github.com/nitrictech/suga/issues](https://github.com/nitrictech/suga/issues)** + +Please search existing issues before creating a new one. + +## Enterprise Support + +Need dedicated support for your organization? + +Contact us about enterprise support options including: +- Priority support response times +- Dedicated Slack channel +- Architecture consulting +- Custom platform development +- Training for your team + +**Email:** [sales@addsuga.com](mailto:sales@addsuga.com) + +## Security Issues + +For security vulnerabilities, please email directly rather than opening public issues: + +**[support@addsuga.com](mailto:support@addsuga.com)** + +Subject: "SECURITY - [Brief Description]" + +## Community + +Connect with other Suga users: + +- **GitHub Discussions** - [github.com/nitrictech/suga/discussions](https://github.com/nitrictech/suga/discussions) +- **Twitter/X** - [@sugasrc](https://twitter.com/sugasrc) + +## Documentation Feedback + +Found an issue with the documentation? + +- **GitHub Issues** - Report doc problems +- **Email** - [support@addsuga.com](mailto:support@addsuga.com) + +Help us improve by being specific about what's unclear or incorrect. + +## Sales & Partnerships + +For business inquiries: + +**Email:** [sales@addsuga.com](mailto:sales@addsuga.com) diff --git a/docs/why-suga.mdx b/docs/why-suga.mdx new file mode 100644 index 00000000..74e7c047 --- /dev/null +++ b/docs/why-suga.mdx @@ -0,0 +1,176 @@ +--- +title: "Why Suga?" +description: "Understanding when and why to use Suga for cloud infrastructure" +--- + +Suga bridges the gap between developer productivity and enterprise control. It combines visual infrastructure design with platform-driven governance to deliver fast, production-ready deployments while maintaining complete flexibility and control. + +## What Makes Suga Different? + +Suga takes a unique approach to cloud infrastructure by combining three key capabilities: + +**Visual Design with Code Generation** +- Design your architecture visually in an intuitive editor +- Generate production-ready Terraform automatically +- Maintain full control over the generated infrastructure + +**Platform-Driven Governance** +- Platform teams define reusable blueprints and standards +- Developers get guardrails, not blockers +- Organizations enforce policies while enabling velocity + +### Visual Design + Generated Infrastructure + +Design your architecture visually, then generate production-ready Terraform. No more choosing between developer experience and infrastructure control. + + + +```yaml title="Design becomes configuration" +entrypoints: + api: + routes: + /: + name: frontend + /api/: + name: app + +services: + app: + dev: + script: npm run dev + frontend: + dev: + script: npm run dev + +buckets: + bucket: + access: + app: [read, write] +``` + +```bash title="Configuration becomes Terraform" +suga build +# ✓ Terraform generated successfully +# output written to terraform/stacks/my-app +``` + +### Platform-Driven Governance + +Platform teams create reusable blueprints that enforce organizational standards while delivering seamless developer experiences. + +**For Developers:** +- Visual infrastructure design +- Local development with emulated cloud services +- Deploy anywhere without changing code +- Generated type-safe client libraries (Node.js, Python, Go, etc) + +**For Platform Teams:** +- Enforce security policies and compliance +- Control cloud resource configurations +- Standardize architectures across teams +- Audit and govern all deployments + +### True Multi-Cloud + +Not just provider-agnostic abstractions - Suga generates native Terraform for each cloud provider while keeping your application code portable. + +```yaml title="Same application, different clouds" +# Deploy to AWS +target: suga/aws@1 + +# Or deploy to GCP +target: suga/gcp@1 +``` + +The generated Terraform uses native cloud resources (Lambda, Cloud Run, S3, Cloud Storage) with proper networking, IAM, and security configurations. + +## How is Suga Different? + +### vs. Developer Platforms + +Suga provides a similar developer experience to hosted platforms while giving you complete control over the generated infrastructure. + +| Aspect | Hosted Platforms | Suga | +|--------|-----------------|------| +| **Deployment Speed** | Instant | Instant (after first Terraform apply) | +| **Infrastructure Control** | Platform-managed | Complete (generated Terraform) | +| **Cloud Provider** | Platform-specific | Multi-cloud (AWS, GCP, Azure, custom) | +| **Customization** | Platform-limited | Full platform customization | +| **Local Development** | Platform-dependent | Full local emulation | +| **Cost Model** | Platform pricing | Direct cloud provider rates | +| **Governance** | Platform-dictated | Organization-controlled | + +**Use Suga if:** You want great developer experience but need full control, multi-cloud support, or enterprise governance. + +### vs. Infrastructure as Code (Terraform/Pulumi) + +Suga builds on top of IaC tools rather than replacing them. It generates standard Terraform that you can inspect, modify, and manage with your existing workflows. + +| Aspect | Direct Terraform/Pulumi | Suga | +|--------|------------------------|------| +| **Approach** | Write infrastructure code | Generate from high-level design | +| **Visual Design** | External tools | Built-in visual editor | +| **Local Development** | Manual setup | `suga dev` | +| **Reusability** | Modules (per-project) | Platforms (organization-wide) | +| **Standardization** | Code reviews & guidelines | Platform-enforced patterns | +| **Flexibility** | Complete control | Extensible platforms + direct Terraform access | + +**Use Suga if:** You want to maximize reuse across teams, enforce organizational standards, or accelerate delivery with visual design while keeping Terraform's flexibility. + +**Use Suga with Terraform if:** You need both platform standardization and custom infrastructure - Suga generates Terraform you can augment with custom resources. + +### vs. Nitric (Suga's Inspiration) + +Suga is built by the team behind [Nitric](https://nitric.io) and incorporates lessons from years of cloud framework development. + +| Aspect | Nitric | Suga | +|--------|--------|------| +| **Approach** | Code-first | Configuration-first | +| **Infrastructure Definition** | Application code annotations | Separate `suga.yaml` + visual editor | +| **Deployment** | Pulumi or Terraform | Terraform | +| **Visual Design** | None | Core feature | +| **Platform System** | Provider plugins | Distributed platform packages | +| **Target Audience** | Developer-focused | Multi-role teams (platform engineers, SREs, DevOps, developers) | + +**Use Suga if:** You work in organizations with multiple roles (platform teams, SREs, DevOps, developers) who need specialized tooling for their responsibilities. + +**Use Nitric if:** You're a developer team that prefers defining infrastructure directly in application code. + +## When to Use Suga + +### ✅ Ideal Use Cases + +**Enterprise Development Teams** +- Need developer velocity without sacrificing governance +- Want to standardize infrastructure across multiple teams +- Require audit trails and compliance controls + +**Multi-Cloud Strategies** +- Building portable applications across clouds +- Avoiding vendor lock-in +- Testing different cloud providers + +**Platform Engineering** +- Creating internal developer platforms +- Enforcing organizational standards +- Providing self-service infrastructure + +**Greenfield Projects** +- Starting new applications with best practices +- Want rapid iteration with production-ready infrastructure +- Need local development that matches production + +## Getting Started + +Ready to try Suga? Start with our [Quickstart Guide](/quickstart) to deploy your first application in minutes. + +Want to understand how Suga works? Explore the [Core Concepts](/core/overview) section to learn about projects, platforms, and infrastructure generation. + +Building an internal platform? Check out the [Platform Development Guide](/guides/build-platform) to create custom platforms for your organization. + + + **Need help deciding?** Contact [support@addsuga.com](mailto:support@addsuga.com) to discuss your use case and whether Suga is a good fit. +