Getting Started with FreeState

Get your Terraform backend hosted on FreeState in under 5 minutes. This guide walks you through account setup, configuration, and your first deployment.

Prerequisites

  • Terraform 0.12+ installed on your machine
  • An existing Terraform project or willingness to create a new one
  • Basic knowledge of Terraform backends

Step 1: Create Your Account

First, sign up for a free FreeState account:

  1. Visit app.freestate.cloud/signup
  2. Enter your email address and create a secure password
  3. Verify your email address
  4. Complete your profile setup

Free Tier Includes

  • 5GB state storage
  • 100 state operations per month
  • Community support
  • Basic state locking

Step 2: Generate API Credentials

Once logged in, you'll need to create API credentials:

  1. Navigate to your dashboard
  2. Go to Settings → API Keys
  3. Click "Generate New API Key"
  4. Give your key a descriptive name (e.g., "terraform-backend")
  5. Copy and securely store your API key

Security Note

Treat your API key like a password. Never commit it to version control or share it publicly. Consider using environment variables or Terraform Cloud's variable management.

Step 3: Configure Terraform Backend

Update your Terraform configuration to use FreeState as the backend. Add this configuration to your main.tf or create a new backend.tf file:

terraform {
  required_version = ">= 0.12"
  
  backend "http" {
    address        = "https://api.freestate.cloud/v1/state/YOUR_WORKSPACE"
    lock_address   = "https://api.freestate.cloud/v1/state/YOUR_WORKSPACE/lock"
    unlock_address = "https://api.freestate.cloud/v1/state/YOUR_WORKSPACE/lock"
    username       = "YOUR_USERNAME"
    password       = "YOUR_API_KEY"
  }
}

Replace the placeholders with your actual values:

  • YOUR_WORKSPACE: A unique name for your workspace (e.g., "my-app-prod")
  • YOUR_USERNAME: Your FreeState username or email
  • YOUR_API_KEY: The API key you generated in step 2

Step 4: Initialize and Migrate

Initialize your Terraform configuration with the new backend:

# Initialize with the new backend
$ terraform init

# If migrating from another backend, use:
$ terraform init -migrate-state

# Verify the backend is working
$ terraform plan

If you're migrating from an existing backend, Terraform will ask if you want to copy your existing state. Answer "yes" to migrate your state to FreeState.

Step 5: Test Your Setup

To verify everything is working correctly:

  1. Run terraform plan to ensure Terraform can read your state
  2. Make a small, safe change to your infrastructure
  3. Run terraform apply to test state writing
  4. Check your FreeState dashboard to see the updated state

Explore the APIs

FreeState provides two comprehensive REST APIs with complete OpenAPI specifications:

Core API

Terraform HTTP backend protocol for state management

  • 📍 Endpoint: api.freestate.cloud
  • 📖 Spec: spec.freestate.cloud
  • 🎯 Use for: Terraform backend operations

Portal API

Administration API for users, workspaces, and billing

Visit the interactive API viewers to explore endpoints, try API calls, and download OpenAPI specs for code generation.

Next Steps

API Reference

Complete documentation for both Core and Portal APIs with examples and authentication guides.

Advanced Terraform Setup

Learn about workspaces, environment variables, and advanced configuration options.

Security Best Practices

Secure your infrastructure with proper access controls and security practices.

Need Help?

If you run into any issues during setup: