LocalCloud

https://local.cloud/docs
Admin
LocalCloud is a local development runtime and CLI that emulates Google Cloud Platform (GCP) services...
Tokens:18,887
Snippets:221
Trust Score:3.3
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install and start LocalCloud

Source: https://local.cloud/docs/localcloud-vs-google-emulators

Run these commands in a terminal to install LocalCloud, check its status, start it, set up environment variables, and open the console. The CLI binds to loopback and can remap occupied canonical ports. Trust the generated environment values.

```shell
curl -fsSL https://local.cloud/install.sh | sh
localcloud doctor
localcloud start
eval "$(localcloud env)"
localcloud consoleCopy
```

--------------------------------

### Start LocalCloud runtime and load environment variables

Source: https://local.cloud/docs/sdk-examples

Run these commands in the same shell before executing any SDK example. Do not hard-code canonical ports; occupied ports may be remapped. Use the generated variables or inject them into the test process.

```bash
localcloud start
eval "$(localcloud env)"
```

--------------------------------

### Start with Explicit Configuration File

Source: https://local.cloud/docs/configuration

Command to start LocalCloud using a specific configuration file path.

```bash
localcloud start ./config/personal-localcloud.yaml
```

--------------------------------

### Install Python Cloud Storage client

Source: https://local.cloud/docs

Install the required Python library to interact with the LocalCloud storage service.

```bash
python -m pip install google-cloud-storage
```

--------------------------------

### Install LocalCloud CLI via install script

Source: https://local.cloud/docs

Downloads and installs the LocalCloud CLI for macOS or Linux. The script performs checksum verification and validates archive members.

```bash
curl -fsSL https://local.cloud/install.sh | sh
```

--------------------------------

### Install LocalCloud CLI via Homebrew

Source: https://local.cloud/docs

Installs the LocalCloud CLI using the Homebrew package manager.

```bash
brew install LocalGCloud/tap/localcloud
```

--------------------------------

### Manual Docker Compose setup

Source: https://local.cloud/docs/configuration

A loopback-only configuration for hosts where the CLI is unavailable, using canonical service ports.

```yaml
services:
  localcloud:
    image: jaysen2apache/localcloud:latest
    ports:
      - "127.0.0.1:24080-24092:24080-24092"
    environment:
      LOCALCLOUD_PROJECT: local-gcp-project
    volumes:
      - localcloud-data:/var/lib/localcloud
    deploy:
      resources:
        limits:
          memory: 4g

volumes:
  localcloud-data:
```

--------------------------------

### Start the LocalCloud runtime

Source: https://local.cloud/docs

Initializes the runtime using defined precedence rules for data volumes and configurations. Use --verbose to inspect the full runtime payload.

```bash
localcloud start
```

--------------------------------

### Define localcloud.yaml Configuration

Source: https://local.cloud/docs/configuration

Example of the versioned configuration structure for project context, host resources, and service settings.

```yaml
version: 1

context:
  project: local-gcp-project
  user: local-developer

host:
  data_volume: localcloud-data
  seed: auto
  data: persistent
  memory: 4g
  transparent_network: false
  environment: {}

services:
  enabled: default

server:
  logging:
    verbosity: info
```

--------------------------------

### Cloud Storage Python example

Source: https://local.cloud/docs/sdk-examples

Repeatable against a persistent local volume. Creates a bucket if it does not exist, uploads a string, and downloads it back. Requires the google-cloud-storage library.

```python
from google.api_core.exceptions import NotFound
from google.cloud import storage

client = storage.Client(project="local-gcp-project")
bucket = client.bucket("localcloud-sdk-example")

try:
    bucket.reload()
except NotFound:
    bucket.create()

blob = bucket.blob("data.txt")
blob.upload_from_string("Hello from LocalCloud!")
print(blob.download_as_text())
```

--------------------------------

### Cloud Storage Node.js example

Source: https://local.cloud/docs/sdk-examples

Uses the @google-cloud/storage client. Checks if the bucket exists, creates it if not, saves a file, and downloads it. Handles errors by setting the process exit code.

```javascript
const { Storage } = require('@google-cloud/storage');

const storage = new Storage({ projectId: 'local-gcp-project' });
const bucket = storage.bucket('localcloud-sdk-example');

async function main() {
  const [exists] = await bucket.exists();
  if (!exists) await storage.createBucket(bucket.name);
  await bucket.file('data.txt').save('Hello from LocalCloud!');
  const [content] = await bucket.file('data.txt').download();
  console.log(content.toString());
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

--------------------------------

### Expected API output

Source: https://local.cloud/docs

The standard output returned after successfully running the API example.

```text
Hello, LocalCloud!
```

--------------------------------

### Run Local Cloud container with Docker

Source: https://local.cloud/docs

Creates a persistent volume and starts the Local Cloud container with specific port mappings and memory limits.

```bash
docker volume create localcloud-data

docker run -d --name localcloud \
  -p 127.0.0.1:24080-24092:24080-24092 \
  -m 4g \
  -v localcloud-data:/var/lib/localcloud \
  jaysen2apache/localcloud:latest
```

--------------------------------

### Check Docker status with localcloud doctor

Source: https://local.cloud/docs

Verifies that a usable Docker installation exists. It does not install or start Docker services; use --verbose for the full JSON payload.

```bash
localcloud doctor
```

--------------------------------

### Verify LocalCloud CLI version

Source: https://local.cloud/docs

Confirms the installed version of the LocalCloud CLI.

```bash
localcloud —version
```

--------------------------------

### Pub/Sub Python example

Source: https://local.cloud/docs/sdk-examples

Pub/Sub state is volatile across emulator restarts. Uses stable names and tolerates resources that already exist. Creates a topic and subscription, publishes a message, pulls it, and acknowledges.

```python
from google.api_core.exceptions import AlreadyExists
from google.cloud import pubsub_v1

project = "local-gcp-project"
publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic = publisher.topic_path(project, "localcloud-sdk-topic")
subscription = subscriber.subscription_path(project, "localcloud-sdk-sub")

try:
    publisher.create_topic(request={"name": topic})
except AlreadyExists:
    pass

try:
    subscriber.create_subscription(request={"name": subscription, "topic": topic})
except AlreadyExists:
    pass

publisher.publish(topic, b"Hello, Pub/Sub!").result()
response = subscriber.pull(request={"subscription": subscription, "max_messages": 1})
for received in response.received_messages:
    print(received.message.data.decode())
    subscriber.acknowledge(
        request={"subscription": subscription, "ack_ids": [received.ack_id]}
    )
```

--------------------------------

### BigQuery deterministic query example

Source: https://local.cloud/docs/sdk-examples

BigQuery behavior is release-unverified until the dependency source and assembled LocalCloud image are identified and qualified together. Uses AnonymousCredentials and a deterministic query. Asserts the result equals 1.

```python
from google.auth.credentials import AnonymousCredentials
from google.cloud import bigquery

client = bigquery.Client(
    project="local-gcp-project",
    credentials=AnonymousCredentials(),
)
rows = list(client.query("SELECT 1 AS ok").result())
assert rows[0].ok == 1
```

--------------------------------

### Cleanup and production validation commands

Source: https://local.cloud/docs/terraform

Run terraform destroy to remove resources, unset the GOOGLE_APPLICATION_CREDENTIALS environment variable, and start a clean process before validating against real Google Cloud.

```bash
terraform destroy -auto-approve
unset GOOGLE_APPLICATION_CREDENTIALS
# Start a clean process before any real-Google-Cloud validation.
```

--------------------------------

### Open the console with the host CLI

Source: https://local.cloud/docs/console

Run this command to open the web console for the selected runtime. Trust the URL printed by the CLI because the gateway may be dynamically remapped from the canonical port 24080. Manual-Docker users on canonical ports can open http://localhost:24080.

```bash
localcloud console
```

--------------------------------

### Enable Default Services

Source: https://local.cloud/docs/configuration

Configuration snippet to use the built-in default set of services.

```yaml
services:
  enabled: default
```

--------------------------------

### Configure server runtime settings

Source: https://local.cloud/docs/configuration

Settings defined under the server key are merged with runtime defaults to control persistence, seeding, IAM mode, and logging.

```yaml
version: 1
server:
  persistence: true
  auto_seed: true
  iam:
    mode: permissive
  logging:
    verbosity: debug
```

--------------------------------

### Mount Seed and Persistent Data with Docker

Source: https://local.cloud/docs/seed-data

Commands to create a persistent volume and run the localcloud container with the seed.yaml file mounted as read-only.

```bash
docker volume create localcloud-data

docker run -d --name localcloud \
  -p 127.0.0.1:24080-24092:24080-24092 \
  -m 4g \
  -v "$PWD/seed.yaml:/etc/localcloud/seed.yaml:ro" \
  -v localcloud-data:/var/lib/localcloud \
  jaysen2apache/localcloud:latest
```

--------------------------------

### Load seed data with curl POST /seed

Source: https://local.cloud/docs/seed-data

Loads a YAML seed file to the root operator endpoint. The canonical gateway URL applies to manual Docker; with the host CLI, derive the actual gateway URL from localcloud start, localcloud status, or localcloud env because port 24080 can be remapped.

```bash
curl -fsS -X POST http://localhost:24080/seed \
  -H 'Content-Type: application/yaml' \
  --data-binary @seed.yaml
```

--------------------------------

### Verify runtime and configure shell

Source: https://local.cloud/docs

Checks the health endpoint and evaluates the environment variables into the current shell session.

```bash
curl -fsS http://localhost:24080/health
eval "$(curl -fsS 'http://localhost:24080/env?format=shell')"
```

--------------------------------

### Enable Specific Services

Source: https://local.cloud/docs/configuration

Configuration snippet to explicitly list only the required services.

```yaml
services:
  enabled:
    - gcs
    - firestore
    - pubsub
```

--------------------------------

### Inspect service status and logs

Source: https://local.cloud/docs/faq

Use these commands to check the status of services, view recent logs, and query the service state endpoint.

```bash
localcloud status
localcloud logs --tail 50
curl -fsS http://localhost:24080/services
```

--------------------------------

### Connect to Spanner emulator with Python SDK

Source: https://local.cloud/docs/spanner-emulator-features

Connects to the LocalCloud Spanner emulator using the official Python SDK. Set SPANNER_EMULATOR_HOST to localhost:24085 and create the instance and database through the Spanner API before running the query. Do not replace this with a PostgreSQL-wire URL.

```python
import os
from google.cloud import spanner

os.environ["SPANNER_EMULATOR_HOST"] = "localhost:24085"

client = spanner.Client(project="local-gcp-project")
instance = client.instance("test-instance")
database = instance.database("test-database")

with database.snapshot() as snapshot:
    rows = snapshot.execute_sql("SELECT 1 AS value")
    print(list(rows))
```

--------------------------------

### Generate environment variables for application connectivity

Source: https://local.cloud/docs/configuration

Use these commands to retrieve environment variables for connecting applications, ensuring host port remapping is accounted for.

```bash
eval "$(localcloud env)"
localcloud env --format json
localcloud env --format terraform
localcloud env --format docker-compose
```

--------------------------------

### Configure TLS and transparent networking

Source: https://local.cloud/docs/configuration

Enables TLS and transparent networking in the configuration file. Transparent mode requires privileged host changes and certificate trust.

```yaml
version: 1
host:
  transparent_network: true
tls:
  enabled: true
  port: 24443
```

--------------------------------

### Select another project with curl

Source: https://local.cloud/docs/sdk-examples

Manual-Docker users can select an explicit project in the request. Keep client project IDs consistent with the generated GOOGLE_CLOUD_PROJECT value.

```bash
eval "$(curl -fsS 'http://localhost:24080/env?format=shell&project=my-local-project')"
```

--------------------------------

### POST /import

Source: https://local.cloud/docs/seed-data

Alias of /seed. Loads a YAML body to seed service data.

```APIDOC
## POST /import

### Description
Alias of /seed. Loads a YAML body to seed service data.

### Method
POST

### Endpoint
/import

### Parameters
#### Request Body
- **body** (YAML) - Required - The YAML fixture data to load.

### Request Example
```
curl -fsS -X POST http://localhost:24080/import \
  -H 'Content-Type: application/yaml' \
  --data-binary @seed.yaml
```

### Response
#### Success Response (200)
No response body is documented.

```

--------------------------------

### Configure shell environment with localcloud env

Source: https://local.cloud/docs

Discovers the running container and exports local-only SDK settings to the current shell. It prevents routing to real Google endpoints.

```bash
eval "$(localcloud env)"
```

--------------------------------

### Apply CLI-managed environment overrides

Source: https://local.cloud/docs/configuration

Use the host.environment key to specify environment variables that the CLI should manage.

```yaml
host:
  environment:
    LOCALCLOUD_TELEMETRY: "false"
```

--------------------------------

### Create fake local credentials

Source: https://local.cloud/docs/terraform

Generates a private key and a fake service-account JSON for local development. These credentials are fake and must never be uploaded or reused for Google Cloud. The helper script is provided in the site repository for a deterministic, JSON-safe credential fixture. Add `.localcloud/` to `.gitignore` in projects that copy this workflow.

```bash
mkdir -p .localcloud
openssl genrsa -out .localcloud/fake-key.pem 2048 2>/dev/null
node scripts/create-localcloud-fake-sa.mjs \
  .localcloud/fake-key.pem \
  .localcloud/fake-service-account.json
chmod 600 .localcloud/fake-key.pem .localcloud/fake-service-account.json
export GOOGLE_APPLICATION_CREDENTIALS="$PWD/.localcloud/fake-service-account.json"
```

--------------------------------

### Generate LocalCloud endpoint variables

Source: https://local.cloud/docs/terraform

Fetches the complete endpoint values from the running LocalCloud runtime and evaluates them in the current shell. The output is derived from the enabled runtime registry and may include additional facade-specific paths. Do not hand-maintain a complete endpoint table.

```bash
eval "$(curl -fsS 'http://localhost:24080/env?format=terraform')"
```

--------------------------------

### Perform idempotent API call

Source: https://local.cloud/docs

This script creates a bucket and uploads a file, overwriting existing data to ensure idempotency. It requires the environment to be configured via localcloud env.

```python
from google.api_core.exceptions import NotFound
from google.cloud import storage

client = storage.Client(project="local-gcp-project")
bucket = client.bucket("localcloud-quickstart")

try:
    bucket.reload()
except NotFound:
    bucket.create()

blob = bucket.blob("hello.txt")
blob.upload_from_string("Hello, LocalCloud!")
print(blob.download_as_text())
```

--------------------------------

### Verify and manage runtime status

Source: https://local.cloud/docs

Commands to check the status and view logs of the LocalCloud runtime.

```bash
localcloud status --verbose
localcloud logs --tail 50
```

--------------------------------

### Configure data volume in host settings

Source: https://local.cloud/docs/configuration

Define a custom Docker volume in the host configuration to isolate local data.

```yaml
host:
  data_volume: localcloud-experiment
```

--------------------------------

### Override project and user context via CLI

Source: https://local.cloud/docs/configuration

Use the --project-id and --user flags to override default context settings for specific commands.

```bash
localcloud start --project-id personal-demo --user alice
eval "$(localcloud env --project-id personal-demo --user alice)"
```
Tokens:
Raw