# Amazon Web Services (AWS) Source: https://docs.localops.co/accounts/aws To connect your **Amazon Web Service (AWS)** cloud account with your LocalOps account you must create a Connection in LocalOps. ## Connections A connection represents LocalOps's access to the target cloud account. All operations performed by LocalOps on a target cloud account, are done through its corresponding connection. ## Pre-requisites 1. AWS account. 2. You'll need to have console access to the target AWS cloud account with Administrator acccess. If you are connecting your client/customer's AWS account, the point of contact in your customer's end must have AWS console access with Administrator access. ## Create a new connection ### To your cloud account 1. Sign in to LocalOps. 2. Click on **"Connections"** from the navigation pane on the left side. 3. Click on **"Add connection"** button to create a new connection. 4. In the next screen, click on "Connect AWS account" button. 5. You will be taken to AWS > CloudFormation console. In that screen, scroll down to click on "Create stack". **Please do not change any value in Create stack screen you see inside AWS. Each of the values represent your account and they must not be changed**. Once you see the stack creation complete, come back to LocalOps to see the connection becoming Active. We create a new cloudformation stack to repesent our acesss. The stack will create a new OIDC provider, IAM role and attach it with relevant permissions for us to access your AWS account. Please read further below to know how this works. ### To your customer cloud account 1. Sign in to LocalOps. 2. Click on **"Connections"** from the navigation pane on the left side. 3. Click on **"Add connection"** button to create a new connection. 4. In the new connection screen, give the connection a name 5. Find the instructions text below th form. Copy and send those instructions to your point of contact at your customer end. 6. Your point of contact or anyone in your customer's end can use the connection link to connect their AWS account with LocalOps. They must have AWS console access with Administrator permissions to complete this process. They must be logged into their AWS account before they can click on the link sent in instructions. In the AWS console, please ask them to click on "Create stack" button. > [!NOTE] > > Please ask them not to change any value in "Create stack" screen inside AWS. Each of the values represent your account > and they must not be changed Once the stack creation is complete, you can come back to LocalOps connections page to see the connection becoming Active. We create a cloudformation stack in the target AWS account to create a new OIDC provider, IAM role and attach it with necessary permissions. Please read further below to know how this works. > [!TIP] > > If you are deploying your app(s) on your customer's cloud environment, we recommend asking your customer to > create a brand new AWS sub-account to connect with LocalOps. This is a best practice to isolate other resources they may > have in their existing AWS account. You can connect resources/services from any two AWS accounts via VPC peering, later > when required. > > If you have a pre-existing AWS Organization setup, follow > [these instructions](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_accounts_create.html) to > create a new AWS sub-account. If not, sign up for a new AWS account here - > [AWS Signup](https://signin.aws.amazon.com/signup?request_type=register). ## How does this access work? LocalOps connects to the target AWS account through a *secure key-less role-based method* recommended by AWS. This method is secure because there are no long-term access keys generated/used during the access. All access is powered by short term keys generated by AWS and given to LocalOps at the specific time of access, every single time. For this to work: 1. A new OIDC provider pointing at LocalOps OIDC server, is created in your AWS account establishing a trust between LocalOps servers and your AWS account. 2. A new IAM role is also created with specific permissions (see below) to let identities outside your AWS account (in this case, LocalOps server) to assume later and get relevant access. 3. Whenever LocalOps wants to connect to your AWS account and perform any operation (say a new deployment), LocalOps would assume the above IAM role by using an identity authorised via the OIDC provider and requests short term keys from AWS sessions service. Your AWS account would generate short term access keys and hands them off to LocalOps servers to use. These access keys are configured to expire in roughly 60-mins or less. 4. Using these keys, LocalOps will access your AWS account to perform any action that you may trigger from LocalOps console. In the steps outlined in "Create a new connection" section, a cloudformation stack is created. This stack does #1 and #2 above to establish a connection with your AWS account. > [!WARNING] > > After connecting the AWS account, DO NOT: > > Remove/modify the cloudformation stack. It holds the OIDC provider, IAM policy and IAM role to keep the cloud connection > alive. > > Remove/modify the IAM role or policy. Again, changes here will break the connection LocalOps has with the target aws > account. ## Permissions required It is ideal to give LocalOps Administrator access in the AWS account you connect. This is automatically setup when you follow the 1-click setup process outlined above. If you require LocalOps to work with lesser permissions, contact us at [support@localops.co](mailto:support@localops.co) to discuss your next steps. You may have to manually set up LocalOps in your cloud with a specific set of permissions, although we don't see this as future proof as we would expand our automation capabilities at LocalOps continuously. ### Required At a minimum, the following permissions are needed in the AWS account to bring up and operate the [core environment](/environment/inside). | AWS Service | Access | Purpose | | - | - | - | | **VPC** | Read+Write | Network isolation for the environment (VPC, public/private Subnets, Internet Gateway, NAT Gateway, Elastic IPs, Route Tables) | | **EC2** | Read+Write | Compute and storage backing the Kubernetes nodes (Security Groups, Launch Templates, EBS volumes, Instances via EKS-managed node groups) | | **EKS** | Read+Write | Managed Kubernetes cluster that runs your services (Cluster, Node Groups, Addons — vpc-cni, coredns, kube-proxy, aws-ebs-csi-driver — Access Entries, Access Policy Associations) | | **IAM** | Read+Write | Roles and policies used by the cluster, nodes and workloads (Roles, Policies, RolePolicyAttachments, OpenID Connect Provider, PassRole) | | **STS** | Read | Issue short-term credentials for LocalOps and IRSA workloads (`AssumeRole`, `AssumeRoleWithWebIdentity`) | | **KMS** | Read+Write | Encryption key for EKS secrets at rest (customer-managed key, ENCRYPT\_DECRYPT) | | **SSM Parameter Store** | Read+Write | Stores service secrets consumed by your workloads (Parameters) | > [!NOTE] > > **You're in full control** > > You are in full control of LocalOps's access to the AWS account. You can disconnect access at any time by deleting > the CloudFormation stack (see [Deleting connections](#deleting-connections)) and reconnect it only when changes need > to be made to the environment. While disconnected, your already-deployed workloads continue to run untouched — > LocalOps simply cannot make any further changes to the AWS account until access is restored. ### Optional These permissions are only required if the corresponding service is declared as a [cloud dependency in `ops.json`](/environment/services/ops-json#automatic-provisioning-of-cloud-resources). | AWS Service | Access | Purpose | | - | - | - | | **S3** | Read+Write | Object storage for service assets and data (Buckets and objects — Get/Put/Delete/List) | | **RDS** | Read+Write | Managed relational databases for services (DB Instances — Postgres/MySQL/SQL Server — Subnet Groups, enhanced-monitoring Role, final snapshots) | | **ElastiCache** | Read+Write | Managed in-memory cache for services (Redis / Memcache Clusters, Subnet Groups) | | **SNS** | Read+Write | Pub/sub messaging for services (Topics — create, publish, subscribe) | | **SQS** | Read+Write | Message queues for services (standard + FIFO Queues — Send/Receive/Delete/GetAttr) | ## Deleting connections You can sign in to LocalOps and delete a connection any time. When you delete a connection, we permanently delete all credentials we hold for that specific cloud account. In addition, you can ensure a full disconnect by deleting the CloudFormation stack we created earlier when setting up the connection. To delete CloudFormation stack in the target AWS account: 1. Sign in to AWS console 2. Go to CloudFormation console in us-east-1 region 3. Select the stack with the name with prefix `Ops-..`, This is the stack we created earlier. 4. Delete the stack This will in turn delete all AWS resources created by the CloudFormation stack. Including IAM role, IAM policy and the OIDC provider, which we used earlier to get access to your AWS account. # Microsoft Azure Source: https://docs.localops.co/accounts/azure We will support Microsoft Azure platform very soon. Talk to us at [support@localops.co](mailto:support@localops.co) to vote for this support. # Connect GitHub account Source: https://docs.localops.co/accounts/connect-github When you use LocalOps, your teams can simply push code to Github repositories to deploy them continuously on their respective environments (staging, production, etc). To provide this push-to-deploy experience, you have to connect the github org/account and its repositories. We need `read-only` access to your github repositories. ### Steps to connect Github org or account > [!NOTE] > > Only organization Owners and Admins can connect GitHub. After that, Owners, Admins and anyone with the Member role in a > project can use its repositories when creating services there. **1. Sign in to LocalOps** **2. Navigate to `Repositories` section** **3. Click on \`+ New Git connection** **4. Follow the on-screen instructions from then to finish connecting your Github org** ### How does this integration work? You must connect your Github organisation or account first, by following above instructions. From inside Github, either during the above integration process or after, you will give us read-only access to specific git repositories. So that LocalOps can listen to all pushes you make on the repository to downlaod the code and deploy. ### Specific repositories While configuring repositories, you can give access to only the specific repositories that has the code you want to deploy. You can also restrict the level of access to `read-only`. # Connect GitLab account Source: https://docs.localops.co/accounts/connect-gitlab Connect gitlab.com or your self-managed GitLab to LocalOps for push-to-deploy, merge request previews, and deployment status. When you use LocalOps, your teams can simply push code to GitLab projects to deploy them continuously on their respective environments (staging, production, etc). To provide this push-to-deploy experience, you have to connect your GitLab account and its projects. LocalOps connects to GitLab over **OAuth 2.0**. Once connected, LocalOps can list your projects and branches, deploy services from them, auto-deploy on push, create preview environments for merge requests, and report deployment status back to GitLab. Two setups are supported: | | Where your code lives | Who owns the OAuth app | | - | - | - | | **LocalOps Cloud (SaaS)** | `gitlab.com` | LocalOps — nothing to register | | **LocalOps Private Instance** | Your self-managed GitLab (GitLab CE/EE, self-hosted, or GitLab Dedicated) | You — register it once on your GitLab | ## How it works At a high level, the integration is a webhook plus a short-lived, read-only clone credential: **1. You authorize LocalOps on GitLab** You grant LocalOps access as a specific GitLab user. LocalOps stores an OAuth token and can then see exactly the projects that user is a member of. **2. You create a service from a project and branch** Your projects and branches show up as options when you create a LocalOps service. You pick which branch each environment tracks. **3. LocalOps registers a webhook on the project** One webhook per project, listening for **push** and **merge request** events. LocalOps creates, reconciles, and removes it for you. **4. A push or merge request arrives** LocalOps verifies the webhook signature, checks that the pusher is a member of your LocalOps organization, and matches the branch against your services. **5. LocalOps clones and deploys** It mints a read-only deploy token that lives only for that build, clones your code, builds it, and deploys to the target environment — then revokes the token. **6. GitLab gets the result back** Deployment status is posted onto the commit, and merge requests get a comment linking to their preview environment. LocalOps never stores a long-lived credential to your source code, and never needs write access to your branches. For the exact objects created in your projects, see [What LocalOps creates in your GitLab projects](#what-localops-creates-in-your-gitlab-projects). ## LocalOps Cloud (SaaS) with gitlab.com ### Before you start You need: * A LocalOps account, signed in as an Owner or Admin of your organization. Only Owners and Admins can connect GitLab. * A **gitlab.com user account** that is a member of the projects you want to deploy. * That user must have at least the **Maintainer** role on each project you intend to deploy. See [What role does my GitLab user need?](#what-role-does-my-gitlab-user-need) below. ### Steps to connect **1. Sign in to LocalOps** **2. Navigate to the `Code repos` section** **3. Click on `Connect GitLab`** **4. Authorize the LocalOps application** You'll be redirected to gitlab.com and asked to authorize the **LocalOps** application with the `api` scope. Review and click **Authorize**. **5. Confirm the connection** You'll land back on the Code repos page with your GitLab account listed as an active connection. That's it. Your projects will now appear when you create a new service and choose GitLab as the source. ### Notes * The connection is tied to **the GitLab user who authorized it**, not to a group. LocalOps sees exactly the projects that user is a member of — nothing more. * The connection is shared across your whole LocalOps organization. Owners, Admins and anyone with the Member role in a project can create services there from the connected projects. * You can connect **more than one** GitLab account to the same LocalOps organization. Each is listed separately. * If you re-authorize with a GitLab account that's already connected, LocalOps refreshes the existing connection instead of creating a duplicate. > [!NOTE] > > **Using gitlab.com is not a requirement of LocalOps Cloud.** If you're on LocalOps Cloud but your code is on a > self-managed GitLab that is reachable from the public internet, you can still connect it — you'll register an OAuth > application on your GitLab as described below, using the LocalOps Cloud redirect URI. Contact support for the exact > redirect URI for your region. ## LocalOps Private Instance with self-managed GitLab If you run LocalOps as a private instance (for example, inside your own VPC), you connect it to your own GitLab by registering an OAuth application on your GitLab and handing LocalOps three values: the **GitLab URL**, the **Application ID**, and the **Secret**. ### Step 1 — Register an OAuth application on your GitLab Choose the scope that matches how widely you want the integration available: | Where to register | Path in GitLab | Use when | | - | - | - | | **Instance-wide** (recommended) | **Admin Area → Applications → New application** | One integration for the whole GitLab instance | | **Group-owned** | **Group → Settings → Applications** | Scope the integration to a single top-level group | | **User-owned** | **User Settings → Applications** | Trying it out, or a single-team pilot | Fill in: | Field | Value | | - | - | | **Name** | `LocalOps` | | **Redirect URI** | `https:///api/v1/callbacks/gitlab/oauth` | | **Confidential** | Checked | | **Scopes** | `api` — and nothing else | Replace `` with the origin your users reach LocalOps at (the same value as your instance's `APP_ORIGIN`). The path must be exactly `/api/v1/callbacks/gitlab/oauth`. Click **Save application**, then copy the **Application ID** and **Secret**. GitLab shows the Secret only once. > [!NOTE] > > **Why the `api` scope?** LocalOps needs to *write* to your projects — register a webhook, mint a short-lived > read-only deploy token for each clone, post merge request comments, and set commit statuses. GitLab's `read_api` and > `read_repository` scopes cannot do any of those. `api` is the narrowest OAuth scope GitLab offers that covers them. > The effective blast radius is bounded by the **role of the user who authorizes**, not by the scope — so connect using > a purpose-made service account rather than an instance administrator. ### Step 2 — Hand the credentials to your LocalOps administrator Give the **GitLab URL**, **Application ID**, and **Secret** from Step 1 to whoever administers your LocalOps instance. They set these three values on the instance: ```bash theme={null} GITLAB_URL=https://gitlab.internal.example.com GITLAB_APP_CLIENT_ID= GITLAB_APP_CLIENT_SECRET= ``` > [!WARNING] > > The Secret is a credential for your GitLab. Send it over a secret manager or another channel your team already trusts > for secrets — not over chat or email. Wait for your administrator to confirm the values are in place before moving on to Step 3. Until then, **Connect GitLab** has nothing to point at and the authorization will fail. ### Step 3 — Connect from LocalOps Once your administrator has configured the instance, connecting is a single click — the GitLab URL and application credentials are already known, so there's nothing to type in. **1. Sign in to LocalOps** **2. Navigate to the `Code repos` section** **3. Click on `Connect GitLab`** **4. Authorize the LocalOps application** You'll be redirected to your GitLab to authorize, then returned to LocalOps with your account listed as an active connection. ### Network and TLS requirements Connectivity has to work in **three** directions. Getting one of these wrong is the most common cause of a failed setup. | Direction | Purpose | Must allow | | - | - | - | | LocalOps → GitLab | OAuth token exchange, project/branch/commit reads, webhook + deploy-token management | HTTPS to your GitLab host | | GitLab → LocalOps | Webhook delivery for push and merge request events | HTTPS to `https:///api/v1/webhooks/gitlab/*` | | Your Space (deployment target) → GitLab | `git clone` during a build | HTTPS to your GitLab host | **TLS:** LocalOps registers webhooks with SSL verification enabled, and validates your GitLab's certificate on outbound API calls. Both endpoints must present a certificate signed by a CA the other side trusts. Self-signed certificates that aren't in the trust store will cause silent webhook delivery failures and API errors. **Clock sync:** Webhook signatures are rejected if the delivery timestamp is more than **5 minutes** off from LocalOps' clock. Keep both hosts on NTP. **GitLab version:** Any actively supported GitLab release works. GitLab **19.0 and later** signs webhook deliveries with an HMAC signature, which LocalOps prefers and verifies automatically. Older versions fall back to a shared-secret token check — also supported, but weaker. No configuration change is needed either way; LocalOps detects and uses the stronger method as soon as your instance supports it. ## What role does my GitLab user need? This applies to **both** setups. The GitLab user who authorizes the connection is the identity LocalOps acts as, so that user's role determines what LocalOps can do. **Minimum: `Maintainer` on every project you want to deploy.** `Owner` also works. Here's why, operation by operation: | What LocalOps does | GitLab API | Minimum role | | - | - | - | | List the projects available to you | `GET /projects?membership=true` | Guest | | List branches, read commits | `GET /repository/branches`, `GET /repository/commits` | Reporter | | Comment on merge requests (preview environment links) | `POST /merge_requests/:iid/notes` | Reporter | | Report deployment status on commits | `POST /statuses/:sha` | Developer | | Create, list, and remove the LocalOps webhook | `.../hooks` | **Maintainer** | | Mint and revoke short-lived clone credentials | `.../deploy_tokens` | **Maintainer** | Only projects where the user is a **Maintainer** or **Owner** can be fully deployed. A project where the user is only a Developer will show up in the list, but webhook registration and clone-credential creation will fail. ### Recommended: use a dedicated service account Rather than connecting a person's account, create a GitLab service account (GitLab Premium/Ultimate) or a dedicated bot user, and add it as a **Maintainer** to only the projects LocalOps should deploy. This gives you: * Least privilege — LocalOps can't see projects you didn't grant. * No breakage when a team member leaves or rotates their credentials. * Clean attribution — LocalOps-created webhooks, tokens, and MR comments are clearly identifiable. > [!WARNING] > > Do **not** connect using an instance administrator account. The `api` scope would then grant LocalOps administrative > reach across your entire GitLab instance. ## One more step: enable auto-deploy for your team **Auto-deploy on push only triggers if the person who pushed is a member of your LocalOps organization, identified through their GitLab account.** LocalOps matches the pusher by their GitLab user ID against LocalOps members who have linked GitLab as a sign-in method. If there's no match, the push is received and logged, but no deployment starts. So, for each team member whose pushes should trigger deploys: 1. They must be a member of your LocalOps organization. 2. They must **sign in to LocalOps with GitLab**, or link GitLab to their existing LocalOps account under account settings. > [!TIP] > > This is a deliberate safety control — it prevents an outside contributor's merged commit from deploying to your > environments. If a push you expected to deploy didn't, this is the first thing to check. ## What LocalOps creates in your GitLab projects Everything below is created automatically and cleaned up automatically. You don't need to configure any of it. **A webhook**, on each project that has at least one LocalOps service: * URL: `https:///api/v1/webhooks/gitlab/` * Events: **Push** and **Merge request** * SSL verification: enabled * Signed with a per-connection secret that LocalOps verifies on every delivery LocalOps keeps exactly one such webhook per project and reconciles continuously — duplicates and hooks left behind by an address change are removed on their own. Webhooks from other LocalOps connections on the same project are never touched. When the last LocalOps service using a project is deleted, the webhook is removed. **A deploy token**, per deployment: * Name: `localops-deploy-` * Scope: `read_repository` only — read-only, and cannot write, delete, or read anything but that project's code * Expires: **48 hours** after creation * Revoked as soon as the deployment reaches a final state A fresh token is minted for every build and thrown away afterwards, so no long-lived credential to your code is ever stored. The 48-hour expiry is a backstop in case revocation is missed. If minting a deploy token fails, LocalOps falls back to the connection's OAuth token for that single clone. ## Disconnecting Go to **Code repos**, open the connection, and click **Disconnect**. The stored tokens and credentials are deleted from LocalOps immediately, and the action is recorded in your audit log. Two things to be aware of: * **Revoke authorization on GitLab too.** Disconnecting in LocalOps deletes LocalOps' copy of the tokens but does not revoke the grant on GitLab's side. To fully revoke, go to your GitLab **User Settings → Applications → Authorized applications** and remove **LocalOps**. * **Webhooks are not removed by disconnecting.** LocalOps needs the connection's credentials to delete a webhook, and disconnecting removes them first. Any remaining LocalOps webhooks on your projects will simply fail to deliver. To clean them up, either delete the LocalOps services using those projects *before* disconnecting, or remove the hooks manually under **Project → Settings → Webhooks** (they'll have a URL containing `/api/v1/webhooks/gitlab/`). Any outstanding deploy tokens expire on their own within 48 hours. ## Troubleshooting **"Failed to exchange OAuth code with GitLab"** The redirect URI on your GitLab OAuth application doesn't match, or the Application ID / Secret is wrong. Confirm the redirect URI is exactly `https:///api/v1/callbacks/gitlab/oauth` — scheme, host, and path all have to match character for character. **"Invalid or expired state. Please try connecting GitLab again."** The authorization took too long, or you opened the authorize link in a different browser session. Start over from **Connect GitLab**. **A project is missing from the list** LocalOps only sees projects where the connected GitLab user is a **member**. Group-level visibility isn't enough — add the user (or your service account) as a member of the project, at Maintainer level. **Service creation fails on webhook registration** The connected user isn't a Maintainer or Owner on that project. Raise the role and retry. **"GitLab connection token expired. Please reconnect GitLab."** LocalOps refreshes access tokens automatically, but the refresh token itself was revoked or expired — usually because someone removed the authorization on GitLab, or the OAuth application's secret was rotated. Reconnect the account. **Pushes don't trigger a deployment** Check, in order: 1. Auto-deploy is enabled on the service. 2. The push was to the branch the service is configured to track. 3. The person who pushed has linked their GitLab account to LocalOps and is a member of your LocalOps organization (see [above](#one-more-step-enable-auto-deploy-for-your-team)). 4. The webhook is delivering — **Project → Settings → Webhooks → Edit → Recent events**. A `401` means a signature mismatch (check clock sync); a timeout or TLS error means GitLab can't reach LocalOps. Note that push deployments are skipped for **Jobs** (one-off tasks) by design, and for branch deletions. # Google Cloud Platform (GCP) Source: https://docs.localops.co/accounts/gcp Connect your Google Cloud account with LocalOps To connect your **Google Cloud Platform (GCP)** account with your LocalOps account, you must create a Connection in LocalOps. ## Connections A connection represents LocalOps's access to the target cloud account. All operations performed by LocalOps on a target cloud account, are done through its corresponding connection. ## Pre-requisites 1. A Google Cloud account. 2. A new Google Cloud project to connect. We recommend creating a brand new project for LocalOps to keep it isolated from your other resources. 3. You'll need `Owner` access to the target Google Cloud project. If you are connecting your client/customer's Google Cloud project, the point of contact in your customer's end must have `Owner` access to the project. ## Create a new connection **1. Add a new connection** Sign in to LocalOps, click on **"Connections"** from the navigation pane on the left side and click on **"Add a new connection"**. **2. Pick Google Cloud** Pick **Google Cloud** as the cloud provider, give the connection a name and click **"Connect GCP account"**. **3. A new Cloud Shell window opens** A new Google Cloud Shell window opens in a separate browser tab. When you open the Cloud Shell tab for the first time, a few popups will show up. **Just authorize and accept all the popups** to continue to Cloud Shell. ![Open in Cloud Shell — check Trust repo and click Confirm](https://mintcdn.com/localops/cKuh7SSJ4WHCOy0q/images/gcp-cloud-shell-trust-repo.png?fit=max\&auto=format\&n=cKuh7SSJ4WHCOy0q\&q=85\&s=90fc8764c15fa160b1115395b0add186) Trust the repo and click Confirm ![Authorize Cloud Shell dialog](https://mintcdn.com/localops/cKuh7SSJ4WHCOy0q/images/gcp-authorize-cloud-shell.png?fit=max\&auto=format\&n=cKuh7SSJ4WHCOy0q\&q=85\&s=34b343a8bace89d1ed65666dd47144f6) Click Authorize to let Cloud Shell make Google Cloud API calls **4. Run the setup command** Go back to the previous LocalOps tab and follow the instructions shown to copy and paste the setup command into the Cloud Shell. Here is a sample of the setup command you will see in the LocalOps console. The values shown below are placeholders — use the exact command displayed in your LocalOps console, as it contains the credentials specific to your connection. ```bash theme={null} export OPS_API_URL="https://console.localops.co" \ OPS_CONNECTION_ID="xxxxxxxxxxxxxxxxxxxxx" \ OPS_VERIFICATION_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" && \ ./setup.sh ``` **5. Pick a Google Cloud project** When the command asks you to pick a Google Cloud project to connect, pick one and proceed. **6. Terraform provisions access** The command runs a Terraform script that creates a new service account with the `Owner` role. This is the service account LocalOps uses to access the project and manage resources henceforth. Once the setup command completes, come back to the LocalOps Connections page to see the connection becoming Active. > [!NOTE] > > When you open the Cloud Shell tab for the first time, a few popups will appear (trust the repo, authorize Cloud > Shell). Just authorize and accept all of them to continue. ## How does this access work? To connect to the target Google Cloud project, the setup command runs a Terraform script inside Google Cloud Shell that creates a new service account with the `Owner` role. LocalOps uses this service account to access the project and manage resources on your behalf whenever you trigger an operation (say a new deployment) from the LocalOps console. The Terraform script that runs in your Cloud Shell to set up the connection is open source and available here: [github.com/localopsco/gcp-connect](https://github.com/localopsco/gcp-connect/). ## Safe and secure Your connection works through a *keyless OIDC protocol*. LocalOps does not store or keep any permanent credentials at its end to access your Google Cloud project. Instead of long-lived keys, access is authenticated on demand through OIDC. Whenever LocalOps needs to access your project, it obtains short-lived credentials just for that operation — there are no static keys sitting around that could be leaked or misused. This makes the connection safe and secure by design. ## Need help? If you have any questions during this process, chat with us from the chat bar on the bottom-right side, or write to us at [support@localops.co](mailto:support@localops.co). # Add Custom Domain Source: https://docs.localops.co/api-reference/custom-domains/add-custom-domain /openapi.json post /v1/environments/{envId}/services/{serviceId}/custom-domains Register a custom domain for a service and get back the DNS records to create. Create the returned records in your DNS provider, then verify the domain. # Delete Custom Domain Source: https://docs.localops.co/api-reference/custom-domains/delete-custom-domain /openapi.json delete /v1/environments/{envId}/services/{serviceId}/custom-domains/{customDomainId} Detach a custom domain from a service and remove it. The domain moves through `delete_queued`, `deleting` and `deleted`, or `delete_failed` on failure. Once an active domain is removed the service is served from its default origin again. > [!WARNING] > > This endpoint is not live yet. The shapes below show how it is expected to work so you can plan your > integration, and may change before release. Calls to this path return `404` today. # Force Deploy Custom Domain Source: https://docs.localops.co/api-reference/custom-domains/force-deploy-custom-domain /openapi.json post /v1/environments/{envId}/services/{serviceId}/custom-domains/{customDomainId}/force-deploy Deploy a custom domain **without** checking its DNS. This is an escape hatch for domains you have verified yourself, when the live DNS check keeps failing. The domain is deployed, its new state is saved, and the service is pointed at it. Because verification is skipped, every force deploy is written to the audit log as `CUSTOM_DOMAIN_FORCE_DEPLOY`. Prefer `verify` for the normal path - it checks DNS and certificate validation first. # Get Custom Domains Source: https://docs.localops.co/api-reference/custom-domains/get-custom-domains /openapi.json get /v1/environments/{envId}/services/{serviceId}/custom-domains Read the service's active and pending custom domain, each hydrated with live DNS records. Note that `data.custom_domain` holds a pair object, not a single domain and not an array. # Verify Custom Domain Source: https://docs.localops.co/api-reference/custom-domains/verify-custom-domain /openapi.json post /v1/environments/{envId}/services/{serviceId}/custom-domains/{customDomainId}/verify Check DNS and certificate validation for the domain and, once verified, deploy its ingress and retire the previously active domain for the service. If DNS has not propagated yet the call returns `500` with `error_code: unknown` rather than a 4xx. Retry verification once the records have propagated. # Cancel Deployment Source: https://docs.localops.co/api-reference/deployments/cancel-deployment /openapi.json post /v1/deployments/{deploymentId}/cancel Stop a deployment that has not finished. Only `queued` and `in_progress` deployments can be canceled. A canceled deployment ends in state `failed`, and its operation ends in state `canceled`. > [!WARNING] > > This endpoint is not live yet. The shapes below show how it is expected to work so you can plan your > integration, and may change before release. Calls to this path return `404` today. # Deploy Service Source: https://docs.localops.co/api-reference/deployments/deploy-service /openapi.json post /v1/environments/{envId}/services/{serviceId}/deploy Trigger a deployment for a specific service within an environment. There are two modes. A **standard deploy** rolls out the service itself and returns a `deployment_id` you can poll. A **preview deploy** (`preview: true`) fans out to a per PR preview service and returns that service instead - preview mode does not return a deployment id. A request body is always required. To deploy the latest commit on a git service's configured branch, send `{}`. The deployment row is created synchronously so the id comes back immediately. The rollout runs in the background and any failure there marks the deployment `failed` rather than failing this request. Preview mode requires the parent service to use the `github` source, be of type `web`, have `enable_previews` turned on, and not itself be a preview service. The account plan must include preview environments. If both `docker_image_tag` and `helm_chart_version` are supplied, `helm_chart_version` wins. # Get Deployment Source: https://docs.localops.co/api-reference/deployments/get-deployment /openapi.json get /v1/deployments/{deploymentId} Poll a deployment. Scoped to your account, so no environment is needed in the path. `success` and `failed` are terminal states. `created_by_id` is the zero UUID for API triggered deployments, and `op_ids` and `ops` are always empty on this endpoint. # Create Environment Source: https://docs.localops.co/api-reference/environments/create-environment /openapi.json post /v1/environments Create an environment in one of your connected cloud accounts. Provisioning runs asynchronously. Follow it by polling `GET /v1/environments/{envId}` until `state` is `available` or `create_failed`, or by following the returned `op_id`. > [!WARNING] > > This endpoint is not live yet. The shapes below show how it is expected to work so you can plan your > integration, and may change before release. Calls to this path return `404` today. # Delete Environment Source: https://docs.localops.co/api-reference/environments/delete-environment /openapi.json delete /v1/environments/{envId} Delete an environment and tear down its infrastructure. The environment moves through `archive_queued`, `archiving` and `archived`, or `archive_failed` on failure. > [!WARNING] > > This endpoint is not live yet. The shapes below show how it is expected to work so you can plan your > integration, and may change before release. Calls to this path return `404` today. # Get Environment Source: https://docs.localops.co/api-reference/environments/get-environment /openapi.json get /v1/environments/{envId} Read an environment's identity, lifecycle state, network edges and workload identity. Three fields exist so you can wire your own infrastructure to the environment, and all three are read live from the environment's infrastructure on every request: - `ingress_host` is the load balancer in front of the environment's ingress. Point your own DNS records at it - a `CNAME` when it is a hostname (AWS), an `A` record when it is an IP address (GCP). - `public_nat_ips` are the NAT gateway addresses the environment's outbound traffic leaves from. Allowlist them in your own firewalls and database security groups. - `svc_role_arn` is the IAM role the environment's pods assume on AWS. Name it as a principal in your own bucket, queue and KMS key policies. It is an identifier and not a credential, so naming it grants nothing until you also set up the trust in your own account. All three are empty until the environment is provisioned. `svc_role_arn` is always empty on GCP, where the equivalent identity is a service account rather than a role. # Health Check Source: https://docs.localops.co/api-reference/health/health-check /openapi.json get /health Unauthenticated liveness check. No `Authorization` header is required. # Get Operation Source: https://docs.localops.co/api-reference/operations/get-operation /openapi.json get /v1/operations/{opId} Read one operation's status and error. Every asynchronous action - a deploy, a delete, a secret write, an environment create - will run as an operation, so a `failed` state comes with the reason instead of leaving you to guess. > [!WARNING] > > This endpoint is not live yet. The shapes below show how it is expected to work so you can plan your > integration, and may change before release. Calls to this path return `404` today. # Get Operation Logs Source: https://docs.localops.co/api-reference/operations/get-operation-logs /openapi.json get /v1/operations/{opId}/logs Read an operation's logs page by page, for example to show build and rollout output in your own CI. To tail an operation, poll with `next_cursor` until the operation reaches a terminal state and a page comes back with `next_cursor: null`. > [!WARNING] > > This endpoint is not live yet. The shapes below show how it is expected to work so you can plan your > integration, and may change before release. Calls to this path return `404` today. # Get Environment Secrets Source: https://docs.localops.co/api-reference/secrets/get-environment-secrets /openapi.json get /v1/environments/{envId}/secrets Read the environment's secret set. Environment level secrets are shared by all services in the environment. # Get Service Secrets Source: https://docs.localops.co/api-reference/secrets/get-service-secrets /openapi.json get /v1/environments/{envId}/services/{serviceId}/secrets Read a service's secret set. Service level secrets are scoped to a single service and are separate from the environment level set. # Replace Environment Secrets Source: https://docs.localops.co/api-reference/secrets/replace-environment-secrets /openapi.json put /v1/environments/{envId}/secrets Replace the environment's entire secret set. This is a full write and not a merge - any key you omit is removed. Read the current set, modify it, then write the whole set back. Keys must be non empty after trimming and unique within the array. Validation runs before anything is written. # Replace Service Secrets Source: https://docs.localops.co/api-reference/secrets/replace-service-secrets /openapi.json put /v1/environments/{envId}/services/{serviceId}/secrets Replace the service's entire secret set. This is a full write and not a merge - any key you omit is removed. Keys must be non empty after trimming and unique within the array. # Create Service Source: https://docs.localops.co/api-reference/services/create-service /openapi.json post /v1/environments/{envId}/services Create a service inside an environment. The service is registered with the provisioner and persisted, service level secrets are optionally seeded, and an immediate first deployment is optionally triggered. The service `subdomain` is generated by LocalOps and cannot be supplied. **`deploy_now`** triggers a deployment right after creation with an empty target - the latest commit on the configured branch for git sources, and the `latest` tag for `docker_image`. No chart version is passed for `helm_chart`, so prefer `deploy_now: false` plus an explicit deploy call with `helm_chart_version`. `deploy_now` does not return a deployment id. If creation succeeds but the deployment fails, the service still exists and the call returns `500` with `Service created successfully, but failed to deploy the service`. # Delete Service Source: https://docs.localops.co/api-reference/services/delete-service /openapi.json delete /v1/environments/{envId}/services/{serviceId} Delete a service. The request creates a delete operation, asks the provisioner to tear the service down and moves the service to `delete_pending`. The teardown itself continues asynchronously. A `202` means the delete was accepted and started. A non 2xx means nothing was torn down. Poll the service status to follow `delete_queued`, `deleting` and `deleted`, or `delete_failed` on failure. For GitLab sourced services LocalOps also removes the project webhook and deploy tokens it created. # Get Service Status Source: https://docs.localops.co/api-reference/services/get-service-status /openapi.json get /v1/environments/{envId}/services/{serviceId} Poll a service's runtime status. This is the only endpoint that hydrates live state from the environment, so `kube_svc_alias`, `kube_secret`, `kube_dep_secret`, `kube_preview_dep_secret`, `namespace_name`, `ops_dependencies` and `ip_whitelist` are populated here and empty or omitted everywhere else. The service is returned twice: as a flat projection at the top of `data`, and in full under `data.service`. The flat fields are **deprecated**. They are kept for existing clients and will be removed once callers read `data.service`. New integrations should use `data.service`, which names the alias `kube_svc_alias` and omits `ip_whitelist` when the service is unrestricted instead of returning `null`. # Update Service Source: https://docs.localops.co/api-reference/services/update-service /openapi.json patch /v1/environments/{envId}/services/{serviceId} Update a service's configuration. Send only the fields you want to change. The database update and the provisioner update run in one transaction. This does not roll the change out - trigger a deployment afterwards. When patching a service whose `type` is `job`, always include `"auto_deploy": false`. Omitting it on a job typed service surfaces as a `500`. # Getting Started Source: https://docs.localops.co/api/getting-started Authentication, response format and error handling for the LocalOps API ## Overview The LocalOps API lets you manage environments, services, deployments, custom domains and secrets programmatically - from the LocalOps SDK, a CLI wrapper or your CI pipeline. It also reads an environment's network edges and workload identity, so you can point your own DNS, firewall allowlists and IAM policies at it. It is a small, deliberately separate surface from the LocalOps console. Every operation the API supports is listed under **Endpoints** in the sidebar. > [!NOTE] > > An **environment** is also referred to as a *Space* in the console. The `envId` path parameter is the environment's > unique identifier. ## Base URL ``` https://sdk.localops.co ``` ## Authentication Every endpoint except `GET /health` requires your account API token, sent as a bearer token: ```bash theme={null} curl -H "Authorization: Bearer YOUR_API_TOKEN" \ https://sdk.localops.co/v1/deployments/3c7a4d81-0000-0000-0000-000000000000 ``` The token is issued per account. Owners and admins can read it from the LocalOps console. > [!WARNING] > > The API token isn't tied to a user, so [roles](/team/understanding-roles) and > [protected environments](/environment/protected-environments) don't limit it. It can act on every project and > environment in the account. Treat it like Owner or Admin access, and keep it in your CI's secret store. A missing header, a non-`Bearer` header, a malformed token, or a token that matches no account are all rejected the same way: ```json theme={null} { "error_code": "unauthorized", "message": "You are not authorized to do this action" } ``` Your account also needs an active plan. If your subscription is not `active` or `past_due`, requests are rejected with `403` and `You don't have an active plan`. Accounts without a subscription, such as BYOC accounts, pass this check. > [!WARNING] > > The API token is the tenancy boundary for every request. Environment, service, deployment and custom domain > identifiers are always looked up within your account, so an identifier belonging to another account behaves exactly > like one that does not exist. ### Attribution in audit logs API requests are not tied to a user. [Audit log](/team/audit-logs) entries for actions taken through the API show **`API Token`** as the actor, and deployments created this way have a zero UUID in `created_by_id`. Service creates, updates and deletes, secret updates, and custom domain creates, verifications and force deploys are all written to the audit log. ## Response format Successful responses are wrapped in an envelope: ```json theme={null} { "message": "success", "data": { "...": "endpoint specific payload" } } ``` There are two exceptions: * `GET /health` returns `{ "message": "ok" }` * `DELETE /v1/environments/{envId}/services/{serviceId}` returns `202 { "message": "accepted" }` ## Errors Errors are **not** wrapped in the `data` envelope: ```json theme={null} { "error_code": "validation", "message": "Invalid data", "errors": [{ "field": "replica_count", "error": "replica_count is a required field" }] } ``` The `errors` array is present only on validation failures, and can be `null` when the failure has no field level detail. | Status | `error_code` | When | | - | - | - | | `401` | `unauthorized` | Missing, malformed or unknown API token | | `403` | `forbidden` | Inactive plan, a deploy on a service being deleted, or a plan without preview environments | | `404` | `notfound` | Unknown environment, service, deployment, custom domain, connection or commit | | `409` | `conflict` | Deleting a protected service | | `422` | `validation` | Field validation failures, a missing or malformed body, duplicate secret keys, a missing image tag or chart version | | `500` | `unknown` | Unexpected failure. Message: `Something went wrong. Please try again later` | | `500` | `validation` | A business rule violation - see below | > [!WARNING] > > Check `error_code` rather than the HTTP status to decide whether a request was at fault. Some business rule > violations, such as `Ops Json is only supported for docker image and helm chart sources` or `Enable Preview is allowed > only for service type web`, are returned as `500` with `error_code: validation`. ### Always send a body Endpoints that accept a request body reject a zero byte body with `422`: ```json theme={null} { "error_code": "validation", "message": "Please check your request body" } ``` Send at least `{}`. This matters most when deploying the latest commit on a git service's configured branch, where there is nothing else to send. ### Rate limits There are no rate limits on the API today. ## Asynchronous work Deployments, service deletes, secret writes and custom domain deploys all hand off to the provisioner. The HTTP response confirms only that the request was accepted and passed synchronous validation. Observe the real outcome by polling: * deployment state, with `GET /v1/deployments/{deploymentId}` * service state, with `GET /v1/environments/{envId}/services/{serviceId}` * custom domain state, with `GET /v1/environments/{envId}/services/{serviceId}/custom-domains` There are no idempotency keys. Retrying a deploy creates another deployment. Retrying a preview deploy for the same pull request reuses the existing preview service, indicated by `is_new: false`, but starts another rollout. ## Coming soon Some endpoints in the sidebar carry a **`COMING SOON`** badge. They are published so you can plan an integration against them, but they are not live yet - those paths return `404` today, and their shapes may change before release. Every asynchronous action will run as an **operation** with its own status, error and logs, so a failure tells you why instead of leaving you to guess. Alongside the two Operations endpoints, this adds an `op_id` to responses you already use, without changing any existing field: | Endpoint | New field | | - | - | | `POST /v1/environments/{envId}/services/{serviceId}/deploy` | `data.op_id`, next to `data.deployment_id` | | `DELETE /v1/environments/{envId}/services/{serviceId}` | `data.op_id` | | `PUT /v1/environments/{envId}/secrets` | `data.op_id` | | `PUT /v1/environments/{envId}/services/{serviceId}/secrets` | `data.op_id` | The `op_ids` and `ops` fields on `GET /v1/deployments/{deploymentId}`, empty today, will be filled in with the deployment's operations at the same time. Creating and deleting environments, deleting a custom domain, and cancelling an in flight deployment are also on the way. ## No list endpoints The API has no "list services" or "list deployments" endpoint. Keep the identifiers returned when you create a service or trigger a deployment, or read them from the console. ## Next steps > **[Common workflows](/api/workflows)** > > End to end recipes for creating and deploying a service, previewing pull requests, wiring services together and > attaching custom domains. The full endpoint reference, with request and response schemas and a live playground, is under **Endpoints** in the sidebar. # License tokens Source: https://docs.localops.co/api/no-access-delivery/license-tokens While your managed deployments via LocalOps works out of the box where you have more control over your customer deployments, you may need to have some control and means of validating and authenticating the deployments that are done via no access delivery. This can be done via License Tokens License tokens can do the following: * Validate your deployment * Provide authentication for your private images * Track usages and deployments for billing purposes * Provides validation api ## Validation API When you create a license token, you can make use of the validation api to control your deployment. You can access this token in your app via `BYOC_LICENSE_TOKEN` environment variable. For example, you can bundle this api in your app and do a start up check to check if the license token is valid and run your services. You can also run a background job to check the status of the license token and stop your services if the license token is expired. API Reference ``` GET https:///licenses/validate ``` > [!NOTE] > > You should set first the custom domain for your company in the LocalOps console. **Authentication** The license token validation endpoint uses Bearer token authentication. You can provide the token in the Authorization header as follows: ``` Authorization: Bearer ``` You will get a `200 OK` response if the token is valid and `401 Unauthorized` if the token is invalid. # Common workflows Source: https://docs.localops.co/api/workflows End to end recipes for the LocalOps API These recipes chain the endpoints in the sidebar. All of them assume the `Authorization: Bearer ` header described in [Getting Started](/api/getting-started), and a base URL of `https://sdk.localops.co`. ## Onboard a bring-your-own-cloud (BYOC) customer - headless The end to end recipe for a [BYOC edition](/use-cases/byoc): your product running inside the customer's own AWS, GCP or Azure account. Every step below is an API call, so onboarding a customer is a script you run once per customer rather than a walk through the console. The recipes further down this page cover each step in more detail. **1. Provision the environment in their cloud** `POST /v1/environments` with the customer's `cloud_connection_id`, the `project_id` to file it under, and the region they want - `aws-us-east-1`, `gcp-us-central1`, and so on. Pass `custom_cidr` when their network team needs the VPC in a particular range. Then poll `GET /v1/environments/{envId}` until `state` is `available`. > [!NOTE] > > `POST /v1/environments` is badged **COMING SOON** and returns `404` today - create the environment in the console > for now. Every step after this one is live. **2. Add your services** `POST /v1/environments/{envId}/services` once per service - API, workers, cron jobs, frontend. Each one can come from a GitHub or GitLab repo, a Docker image or a Helm chart, with its own `replica_count`, CPU and memory. Keep each `data.service.id` - there is no list endpoint to look them up again. Adding a service to a customer later is the same call. See [Create a Helm service and deploy it](#create-a-helm-service-and-deploy-it) and [Deploy a git service from CI](#deploy-a-git-service-from-ci). **3. Set their secrets** `PUT /v1/environments/{envId}/secrets` for values every service in the environment shares, and `PUT /v1/environments/{envId}/services/{serviceId}/secrets` for the ones scoped to a single service. This is where per customer configuration lives - their database URLs, their API keys, their license terms. See [Update secrets safely](#update-secrets-safely) - these writes replace the whole set. **4. Deploy** `POST /v1/environments/{envId}/services/{serviceId}/deploy` with a `commit_id`, a `docker_image_tag` or a `helm_chart_version`, then poll `GET /v1/deployments/{deploymentId}` until `success` or `failed`. See [Deploy a git service from CI](#deploy-a-git-service-from-ci). **5. Attach their domain** `POST /v1/environments/{envId}/services/{serviceId}/custom-domains` returns the exact DNS records for the customer to create. Once they resolve, `POST .../custom-domains/{customDomainId}/verify` checks them and cuts traffic over. See [Attach a custom domain](#attach-a-custom-domain). **6. Hand over the network details** `GET /v1/environments/{envId}` returns the `ingress_host` to point DNS at, the `public_nat_ips` to allowlist and the `svc_role_arn` to name in their resource policies - the three things the customer's network and security teams ask for during review. See [Point your own DNS and allowlists at an environment](#point-your-own-dns-and-allowlists-at-an-environment). ### Ship a release to every customer Once customers are onboarded, a rollout is the same call against each environment id: ```bash theme={null} while read -r ENV_ID SERVICE_ID; do curl -X POST https://sdk.localops.co/v1/environments/$ENV_ID/services/$SERVICE_ID/deploy \ -H "Authorization: Bearer $LOCALOPS_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"docker_image_tag": "1.4.0", "note": "rollout 1.4.0"}' done < customer-envs.txt ``` Each call returns a `deployment_id`, so you can gate the next customer on the previous one reaching `success` and stage the rollout across your install base. > [!TIP] > > Keep a record of every customer's `envId` and `serviceId` as you create them. The API has no list endpoint, so these > identifiers are the only handle you have on a customer's environment. ## Point your own DNS and allowlists at an environment `GET /v1/environments/{envId}` reads three fields live from the environment's infrastructure on every call. They are what you need to connect your own DNS, firewalls and cloud IAM to a LocalOps environment. ```bash theme={null} curl -H "Authorization: Bearer $LOCALOPS_API_TOKEN" \ https://sdk.localops.co/v1/environments/$ENV_ID ``` ```json theme={null} { "message": "success", "data": { "environment": { "state": "available", "cloud_region_code": "aws-us-east-1", "ingress_host": "k8s-ingress-a1b2c3d4.elb.us-east-1.amazonaws.com", "public_nat_ips": ["43.204.246.44"], "svc_role_arn": "arn:aws:iam::123456789012:role/lops-prod-a1b2-svc-role" } } } ``` | Field | What to do with it | | - | - | | `ingress_host` | Point a DNS record at it. A `CNAME` when it is a hostname (AWS), an `A` record when it is an IP address (GCP). | | `public_nat_ips` | Allowlist these addresses in your own firewalls and database security groups. This is where the environment's outbound traffic comes from. | | `svc_role_arn` | Name it as a principal in your own bucket, queue and KMS key policies. **AWS only** - it is always empty on GCP. | All three are empty until the environment is provisioned, so poll until the one you need is set. > [!NOTE] > > `svc_role_arn` is an identifier, not a credential. Naming it in a resource policy grants nothing until you also set up > the trust in your own account. And `public_nat_ips` can change, so re-read it after infrastructure changes rather than > caching it indefinitely. To have LocalOps manage a domain for you instead, with certificates and verification, use [Attach a custom domain](#attach-a-custom-domain) below. ## Create a Helm service and deploy it **1. Create the service** `POST /v1/environments/{envId}/services` with `source: "helm_chart"` and `deploy_now: false`. Keep `deploy_now` off for Helm services. It deploys without a chart version, so an explicit deploy is almost always what you want. ```bash theme={null} curl -X POST https://sdk.localops.co/v1/environments/$ENV_ID/services \ -H "Authorization: Bearer $LOCALOPS_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "name": "checkout api", "type": "web", "source": "helm_chart", "port": 8080, "helm_chart_repo": "https://charts.example.com", "helm_chart_name": "checkout", "helm_values_yml": "replicaCount: 2\n", "deploy_now": false }' ``` Keep `data.service.id` from the response - there is no list endpoint to look it up again. **2. Write service secrets** `PUT /v1/environments/{envId}/services/{serviceId}/secrets`, if the service needs any. **3. Deploy a chart version** `POST /v1/environments/{envId}/services/{serviceId}/deploy` with `{"helm_chart_version": "1.4.0"}`. Keep `data.deployment_id` from the response. **4. Poll the deployment** `GET /v1/deployments/{deploymentId}` until `state` is `success` or `failed`. > [!NOTE] > > Service names on create accept letters and spaces only. Digits, hyphens and underscores are rejected. Updates are > laxer and also allow hyphens. ## Deploy a git service from CI For a GitHub or GitLab service, deploy the head of the configured branch by sending an empty object: ```bash theme={null} curl -X POST https://sdk.localops.co/v1/environments/$ENV_ID/services/$SERVICE_ID/deploy \ -H "Authorization: Bearer $LOCALOPS_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{}' ``` Or pin an exact commit, with an optional note of up to 300 characters: ```json theme={null} { "commit_id": "9f2c1ab", "note": "release 1.4.0" } ``` Then poll `GET /v1/deployments/{deploymentId}`. The deployment row is created synchronously, so you always get an id back immediately even though the rollout itself runs in the background - a rollout failure shows up as `state: "failed"`, not as an error on the deploy call. For a `docker_image` service, send `docker_image_tag` instead. For `helm_chart`, send `helm_chart_version`. ## Deploy a pull request preview **1. Check the parent service** The parent service must use the `github` source, be of type `web`, and have `enable_previews` turned on. Your plan must include preview environments, otherwise the call returns `403`. Turn previews on with `PATCH /v1/environments/{envId}/services/{serviceId}` and `{"enable_previews": true}`. **2. Trigger the preview deploy** ```bash theme={null} curl -X POST https://sdk.localops.co/v1/environments/$ENV_ID/services/$SERVICE_ID/deploy \ -H "Authorization: Bearer $LOCALOPS_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "preview": true, "commit_id": "9f2c1ab", "branch": "feat/checkout-v2", "pr_number": 42 }' ``` `commit_id`, `branch` and `pr_number` are all required in preview mode, and `docker_image_tag` and `helm_chart_version` must be absent. **3. Use the returned preview service** The response carries `service_id`, `service_name`, `origin`, `pr_number` and `is_new` - not a deployment id. A preview service is created for the pull request the first time (`is_new: true`) and reused on later calls (`is_new: false`). It inherits the parent's type, resources, port and node group, and has `auto_deploy` turned on. **4. Poll the preview service** `GET /v1/environments/{envId}/services/{serviceId}` with the returned `service_id`, until `state` is `running`. ## Attach a custom domain **1. Register the domain** `POST /v1/environments/{envId}/services/{serviceId}/custom-domains` with `{"domain": "app.example.com"}`. The response contains `dns_records`, each with `record_name`, `record_type` and `record_value`. **2. Create the DNS records** Add every returned record in your DNS provider - both the certificate validation record and the traffic routing record. **3. Verify** `POST /v1/environments/{envId}/services/{serviceId}/custom-domains/{customDomainId}/verify`. > [!WARNING] > > While DNS is still propagating, verification fails with `500` and `error_code: unknown` rather than a 4xx. Retry > once the records have propagated. **4. Confirm** `GET /v1/environments/{envId}/services/{serviceId}/custom-domains` until `active_domain.state` is `deployed`. Verifying a new domain retires the service's previously active domain. If you have verified the domain yourself and the live DNS check keeps failing, `force-deploy` is the escape hatch: ```bash theme={null} curl -X POST \ https://sdk.localops.co/v1/environments/$ENV_ID/services/$SERVICE_ID/custom-domains/$CUSTOM_DOMAIN_ID/force-deploy \ -H "Authorization: Bearer $LOCALOPS_API_TOKEN" ``` It deploys the domain without checking DNS and points the service at it. Because it skips verification, every call is written to the audit log as `CUSTOM_DOMAIN_FORCE_DEPLOY`. ## Wire one service to another Services inside the same environment reach each other over an in cluster DNS alias. **1. Read the alias** `GET /v1/environments/{envId}/services/{serviceId}` returns `svc_alias`. It is empty until the service is provisioned, so poll until it is set. **2. Publish it as a secret** `PUT /v1/environments/{envId}/services/{serviceId}/secrets` on the consuming service, with the alias as the host - for example `DB_HOST`. **3. Redeploy the consumer** Secret writes do not roll themselves out. Trigger a deployment for the consuming service. The same response carries `ops_dependencies` - the cloud resources the service declares in its [ops.json](/environment/services/ops-json). Each one lists the environment variables it injects, so you can discover what a service already gets without reading its repo: ```json theme={null} { "id": "orders-primary", "kind": "rds", "exports": { "DATABASE_URL": "$dsn", "DB_HOST": "$address" } } ``` The `$...` tokens are resolved when the variables are injected into your container. The API returns them as declared. ## Update secrets safely Both secret endpoints are a **full replacement**, not a merge. Any key you leave out of the array is removed. **1. Read** `GET /v1/environments/{envId}/secrets`, or the service level equivalent. **2. Modify** Change or add entries in the array you just read. Keys must be non empty and unique - a duplicate is rejected with `422` and `Duplicate secret key: `. **3. Write the whole set back** `PUT` the complete array. Validation runs before anything is written, so a rejected request changes nothing. ## Delete a service **1. Remove protection** A protected service returns `409` on delete. Clear it first with `PATCH /v1/environments/{envId}/services/{serviceId}` and `{"is_protected": false}`. > [!WARNING] > > When patching a service whose `type` is `job`, always include `"auto_deploy": false` in the body. Omitting it on > a job typed service surfaces as a `500`. **2. Delete** `DELETE /v1/environments/{envId}/services/{serviceId}` returns `202 {"message": "accepted"}`, meaning the teardown was accepted and started. A non 2xx means nothing was torn down. **3. Poll to completion** `GET /v1/environments/{envId}/services/{serviceId}` through `delete_queued`, `deleting` and `deleted`, or `delete_failed` on failure. # Database Migration Source: https://docs.localops.co/bring-your-helm-charts/database-migration In this guide, we demonstrate how DB migrations can be integrated into Helm charts in such a way that satisfies the principles for deploying schema migrations before starting the application. We will see how to handle both DB schema and data migrations. > [!NOTE] > > We recommend using a robust migration framework for your applications that uses versioned migration files. Most migration frameworks support linear migrations, which only allow progressive changes. > > Therefore, if you need to remove a database column or field introduced in an earlier migration, you must create a new > migration file specifically for this purpose. This approach ensures that all changes are tracked and applied in a > controlled and sequential manner. ## Prerequisites 1. A migrations docker image 2. A Helm chart defining your application. ## Schema Migrations ### Using Helm lifecycle hooks To satisfy the principle of having migrations run before the new application version starts, as well as ensure that **only one migration job runs concurrently**, we use Helm's `pre-install` and `pre-upgrade` hooks feature. > [!NOTE] > > Helm pre-upgrade hooks are chart hooks that: > > Executes on an upgrade request after templates are rendered, but before any resources are updated To use `pre-install` and `pre-upgrade` hooks to run migrations as part of our chart definition, we create a template for a **Kubernetes Job** and annotate it with the relevant Helm hook annotations. **General** ```yaml job.yaml theme={null} apiVersion: batch/v1 kind: Job metadata: # Job name should include a unix timestamp to make sure it's unique name: "{{ .Release.Name }}-migrate-{{ now | unixEpoch }}" labels: helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}" annotations: "helm.sh/hook": pre-install,pre-upgrade "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded spec: template: metadata: name: "{{ .Release.Name }}-db-migrate" labels: app.kubernetes.io/managed-by: {{ .Release.Service | quote }} app.kubernetes.io/instance: {{ .Release.Name | quote }} helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}" spec: restartPolicy: Never imagePullSecrets: - name: {{ .Values.imagePullSecret }} containers: - name: db-migrate # Image to run DB migration image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}" # Command to run DB migration args: - migrate - apply - -u - {{ .Values.dburl }} - --dir - file:///src/ # Environment variables required for migrations to run env: - name: DATABASE_HOST value: {{ .Values.django.env.DATABASE_HOST }} - name: DATABASE_PORT value: {{ .Values.django.env.DATABASE_PORT }} - name: DATABASE_NAME value: {{ .Values.django.env.DATABASE_NAME }} - name: DATABASE_USER value: {{ .Values.django.env.DATABASE_USER }} - name: DATABASE_PASSWORD value: {{ .Values.django.env.DATABASE_PASSWORD }} ``` **Django** ```yaml job.yaml theme={null} apiVersion: batch/v1 kind: Job metadata: # Job name should include a unix timestamp to make sure it's unique name: "{{ .Release.Name }}-migrate-{{ now | unixEpoch }}" labels: helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}" annotations: "helm.sh/hook": pre-install,pre-upgrade "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded spec: template: metadata: name: "{{ .Release.Name }}-db-migrate" labels: app.kubernetes.io/managed-by: {{ .Release.Service | quote }} app.kubernetes.io/instance: {{ .Release.Name | quote }} helm.sh/chart: "{{ .Chart.Name }}-{{ .Chart.Version }}" spec: restartPolicy: Never imagePullSecrets: - name: {{ .Values.imagePullSecret }} containers: - name: migrate # Image to run migration # Incase of Python Django, it is the same image as application image: {{ .Values.django.image.repository }}:{{ .Values.django.image.tag }} # Command to run DB migration command: ["sh", "-c", "python manage.py migrate"] # Environment variables required for migrations to run env: - name: DATABASE_HOST value: {{ .Values.django.env.DATABASE_HOST }} - name: DATABASE_PORT value: {{ .Values.django.env.DATABASE_PORT }} - name: DATABASE_NAME value: {{ .Values.django.env.DATABASE_NAME }} - name: DATABASE_USER value: {{ .Values.django.env.DATABASE_USER }} - name: DATABASE_PASSWORD value: {{ .Values.django.env.DATABASE_PASSWORD }} ``` > [!NOTE] > > Above Job will be run each time when an \[Environment] is created and when a deployment is made with a new helm chart > version. ## Data Migrations Similarly, DB data migrations can be performed within the same migration files and executed sequentially in a consistent order. This approach allows you to manage both schema and data changes together within the same migration framework, ensuring consistency and ease of development and maintenance. > [!TIP] > > LocalOps intends to adopt Blue/Green deployment strategy soon. Therefore, it is advisable to avoid introducing > breaking database or API changes in consecutive deployments. This practice ensures smoother transitions and minimizes > disruptions during version upgrades. **In this article you have learnt how to run DB migrations from your Helm Chart inside [Environment].** 👍🏽 [Environment]: https://console.localops.co/environments # MongoDB Source: https://docs.localops.co/bring-your-helm-charts/databases/mongodb This guide will walk you through the steps to integrate MongoDB into your existing Helm chart for your Kubernetes application. By adding MongoDB, you can leverage its capabilities for NoSQL database management. We will use the Bitnami MongoDB Helm chart as a dependency and configure it accordingly. ## Prerequisites * Helm installed and configured * Kubernetes cluster up and running * Existing Helm chart for your application ## Steps to Integrate MongoDB ### 1. Add MongoDB Helm Repository First, add the Bitnami repository, which hosts the MongoDB Helm chart, ```sh theme={null} helm repo add bitnami https://charts.bitnami.com/bitnami helm repo update ``` ### 2. Update `Chart.yaml` Open your existing Helm chart directory and edit the Chart.yaml file to add MongoDB as a dependency, ```yaml Chart.yaml theme={null} apiVersion: v2 name: your-app description: A Helm chart for your Kubernetes application version: 0.1.0 appVersion: '1.0' dependencies: - name: mongodb version: 13.10.3 repository: https://charts.bitnami.com/bitnami ``` ### 3. Update `values.yaml` Create or update the `values.yaml` file to include configuration values for MongoDB. Customize the values as per your requirements. ```yaml values.yaml theme={null} mongodb: enabled: true auth: rootPassword: myrootpassword username: myuser password: mypassword database: mydatabase primary: persistence: enabled: true size: 50Gi ``` > [!TIP] > > Over-provisioning on disk size (`primary.persistence.size`) isn't a bad idea considering that disks are cheap in any > cloud. It is also slightly trickier to increase volume sizes at later point in time due to some Kubernetes > limitations. So we recommend you pick a good number here from the start. ### 4. Install/Update Dependencies Navigate to your Helm chart directory and run the following command to update dependencies, ```shell theme={null} helm dependency update ``` This command will download the MongoDB chart and add it to your `charts/` directory. ### 5. Update Your Application Deployment Modify your application's deployment files to include the MongoDB service. Ensure your application can connect to MongoDB using the service name and credentials specified in the `values.yaml` file. For example, if using a **ConfigMap** to store environment variables for your application, you might update it like this, ```yaml templates/configmap.yaml theme={null} apiVersion: v1 kind: ConfigMap metadata: name: your-app-config data: DATABASE_HOST: 'your-app-mongodb' DATABASE_PORT: '27017' DATABASE_USER: 'myuser' DATABASE_PASSWORD: 'mypassword' DATABASE_NAME: 'mydatabase' ``` ### 6. Deploy Your Application Finally, deploy or upgrade your application using Helm, ```shell theme={null} helm install your-app ./your-app-chart # or if upgrading an existing release helm upgrade your-app ./your-app-chart ``` ### 7. Verify Deployment Check the status of your Helm release to ensure everything is running correctly, ```shell theme={null} helm status your-app ``` Also, verify that the MongoDB pod is running, ```shell theme={null} kubectl get pods ``` You should see a pod for MongoDB, something like `your-app-mongodb-0`. **Congratulations! You have successfully added MongoDB to your existing Helm chart. 🚀** This integration allows your application to use MongoDB for NoSQL database management, managed efficiently with Helm. Customize the MongoDB configuration further by modifying the `values.yaml` file as needed. For more detailed configurations and advanced settings, refer to the [Bitnami MongoDB Helm chart documentation](https://github.com/bitnami/charts/tree/main/bitnami/mongodb#readme). # MySQL Source: https://docs.localops.co/bring-your-helm-charts/databases/mysql This guide will walk you through the steps to integrate MySQL into your existing Helm chart for your Kubernetes application. By adding MySQL, you can leverage its capabilities for relational database management. We will use the Bitnami MySQL Helm chart as a dependency and configure it accordingly. ## Prerequisites * Helm installed and configured * Kubernetes cluster up and running * Existing Helm chart for your application ## Steps to Integrate MySQL ### 1. Add MySQL Helm Repository First, add the Bitnami repository, which hosts the MySQL Helm chart, ```sh theme={null} helm repo add bitnami https://charts.bitnami.com/bitnami helm repo update ``` ### 2. Update `Chart.yaml` Open your existing Helm chart directory and edit the Chart.yaml file to add MySQL as a dependency, ```yaml Chart.yaml theme={null} # Chart.yaml apiVersion: v2 name: your-app description: A Helm chart for your Kubernetes application version: 0.1.0 appVersion: '1.0' dependencies: - name: mysql version: 9.3.5 repository: https://charts.bitnami.com/bitnami ``` ### 3. Update `values.yaml` Create or update the `values.yaml` file to include configuration values for MySQL. Customize the values as per your requirements. ```yaml values.yaml theme={null} mysql: enabled: true auth: rootPassword: myrootpassword database: mydatabase username: myuser password: mypassword primary: persistence: enabled: true size: 50Gi ``` > [!TIP] > > Over-provisioning on disk size (`primary.persistence.size`) isn't a bad idea considering that disks are cheap in any > cloud. It is also slightly trickier to increase volume sizes at later point in time due to some Kubernetes > limitations. So we recommend you pick a good number here from the start. ### 4. Install/Update Dependencies Navigate to your Helm chart directory and run the following command to update dependencies, ```sh theme={null} helm dependency update ``` This command will download the MySQL chart and add it to your `charts/` directory. 5. Update Your Application Deployment Modify your application's deployment files to include the MySQL service. Ensure your application can connect to MySQL using the service name and credentials specified in the values.yaml file. For example, if using a ConfigMap to store environment variables for your application, you might update it like this, ```yaml templates/configmap.yaml theme={null} apiVersion: v1 kind: ConfigMap metadata: name: your-app-config data: DATABASE_HOST: 'your-app-mysql' DATABASE_PORT: '3306' DATABASE_USER: 'myuser' DATABASE_PASSWORD: 'mypassword' DATABASE_NAME: 'mydatabase' ``` ### 6. Deploy Your Application Finally, deploy or upgrade your application using Helm, ```sh theme={null} helm install your-app ./your-app-chart # or if upgrading an existing release helm upgrade your-app ./your-app-chart ``` ### 7. Verify Deployment Check the status of your Helm release to ensure everything is running correctly, ```sh theme={null} helm status your-app ``` Also, verify that the MySQL pod is running, ```sh theme={null} kubectl get pods ``` You should see a pod for MySQL, something like `your-app-mysql-0`. **Congratulations! You have successfully added MySQL to your existing Helm chart.** 🚀 This integration allows your application to use MySQL for relational database management, managed efficiently with Helm. Customize the MySQL configuration further by modifying the `values.yaml` file as needed. For more detailed configurations and advanced settings, refer to the Bitnami [MySQL Helm chart documentation](https://github.com/bitnami/charts/tree/main/bitnami/mysql#readme). # Postgres Source: https://docs.localops.co/bring-your-helm-charts/databases/postgres This guide will walk you through the steps to add a PostgreSQL database to an existing Helm chart for your Kubernetes application. Helm charts help manage Kubernetes applications using templates, and adding PostgreSQL will involve integrating the Bitnami PostgreSQL Helm chart as a dependency and configuring it appropriately. ## Steps ### 1. Add PostgreSQL Helm Repository First, add the Bitnami repository, which hosts the PostgreSQL Helm chart, ```shell theme={null} helm repo add bitnami https://charts.bitnami.com/bitnami helm repo update ``` ### 2. Update `Chart.yaml` Open your existing Helm chart directory and edit the Chart.yaml file to add PostgreSQL as a dependency, ```yaml Chart.yaml theme={null} apiVersion: v2 name: your-app description: A Helm chart for your Kubernetes application version: 0.1.0 appVersion: '1.0' dependencies: - name: postgresql version: 12.1.9 repository: https://charts.bitnami.com/bitnami ``` ### 3. Update `values.yaml` Create or update the values.yaml file to include configuration values for PostgreSQL. You can customize the values based on your requirements. Refer to [https://github.com/bitnami/charts/blob/main/bitnami/postgresql/README.md#parameters](https://github.com/bitnami/charts/blob/main/bitnami/postgresql/README.md#parameters) for all configuration options provided by PostgresSql helm chart. ```yaml values.yaml theme={null} postgresql: enabled: true global: postgresql: auth: postgresqlPassword: mysecretpassword primary: persistence: enabled: true size: 50Gi ``` > [!TIP] > > Over-provisioning on disk size (`primary.persistence.size`) isn't a bad idea considering that disks are cheap in any > cloud. It is also slightly trickier to increase volume sizes at later point in time due to some Kubernetes > limitations. So we recommend you pick a good number here from the start. ### 4. Install/Update Dependencies Navigate to your Helm chart directory and run the following command to update dependencies, ```shell theme={null} helm dependency update ``` ### 5. Update Your Application Deployment Modify your application's deployment files to include the PostgreSQL service. Ensure your application can connect to PostgreSQL using the service name and credentials specified in the `values.yaml` file. For example, if using a **ConfigMap** to store environment variables for your application, you might update it like this, ```yaml templates/configmap.yaml theme={null} apiVersion: v1 kind: ConfigMap metadata: name: your-app-config data: DATABASE_HOST: {{ .Release.Name }}-postgresql DATABASE_PORT: '5432' DATABASE_USER: 'postgres' DATABASE_PASSWORD: 'mysecretpassword' DATABASE_NAME: 'yourdbname' ``` ### 6. Deploy Your Application Finally, deploy or upgrade your application using Helm, ```shell theme={null} helm install your-app ./your-app-chart # or if upgrading an existing release helm upgrade your-app ./your-app-chart ``` ### 7. Verify Deployment Check the status of your Helm release to ensure everything is running correctly, ```shell theme={null} helm status your-app ``` ##### Also, verify that the PostgreSQL pod is running, ```shell theme={null} kubectl get pods ``` You should see a pod for PostgreSQL, something like `your-app-postgresql-0`. Congratulations! You have successfully added PostgreSQL to your existing Helm chart. This integration allows your application to use PostgreSQL as its database, managed efficiently with Helm. You can further customize the PostgreSQL configuration by modifying the values.yaml file as needed. # Redis Source: https://docs.localops.co/bring-your-helm-charts/databases/redis This guide will walk you through the steps to integrate Redis into your existing Helm chart for your Kubernetes application. By adding Redis, you can leverage its capabilities for caching, session management, and more. We will use the Bitnami Redis Helm chart as a dependency and configure it accordingly. ## Prerequisites * Helm installed and configured * Kubernetes cluster up and running * Existing Helm chart for your application ## Steps to Integrate Redis ### 1. Add Redis Helm Repository First, add the Bitnami repository, which hosts the Redis Helm chart, ```sh theme={null} helm repo add bitnami https://charts.bitnami.com/bitnami helm repo update ``` ### 2. Update `Chart.yaml` Open your existing Helm chart directory and edit the `Chart.yaml` file to add Redis as a dependency, ```yaml Chart.yaml theme={null} apiVersion: v2 name: your-app description: A Helm chart for your Kubernetes application version: 0.1.0 appVersion: '1.0' dependencies: - name: redis version: 17.0.1 repository: https://charts.bitnami.com/bitnami ``` ### 3. Update `values.yaml` Create or update the values.yaml file to include configuration values for Redis. Customize the values as per your requirements. Refer to [https://github.com/bitnami/charts/blob/main/bitnami/redis/README.md#parameters](https://github.com/bitnami/charts/blob/main/bitnami/redis/README.md#parameters) for all the available configuration parameters supported by Redis chart. ```yaml values.yaml theme={null} redis: enabled: true auth: password: myredispassword architecture: standalone master: persistence: enabled: true size: 15Gi ``` > [!TIP] > > Over-provisioning on disk size (`master.persistence.size`) isn't a bad idea considering that disks are cheap in any > cloud. It is also slightly trickier to increase volume sizes at later point in time due to some Kubernetes > limitations. So we recommend you pick a good number here from the start. ### 4. Install/Update Dependencies Navigate to your Helm chart directory and run the following command to update dependencies, ```shell theme={null} helm dependency update ``` This command will download the Redis chart and add it to your charts/ directory. ### 5. Update Your Application Deployment Modify your application's deployment files to include the Redis service. Ensure your application can connect to Redis using the service name and credentials specified in the `values.yaml` file. For example, if using a ConfigMap to store environment variables for your application, you might update it like this, ```yaml templates/configmap.yaml theme={null} apiVersion: v1 kind: ConfigMap metadata: name: your-app-config data: REDIS_HOST: {{ .Release.Name }}-redis-master REDIS_PORT: '6379' REDIS_PASSWORD: 'myredispassword' ``` ### 6. Deploy Your Application Finally, deploy or upgrade your application using Helm, ```shell theme={null} helm install your-app ./your-app-chart # or if upgrading an existing release helm upgrade your-app ./your-app-chart ``` ### 7. Verify Deployment Check the status of your Helm release to ensure everything is running correctly, ```shell theme={null} helm status your-app ``` Also, verify that the Redis pod is running: ```shell theme={null} kubectl get pods ``` You should see a pod for Redis, something like `your-app-redis-master-0`. Congratulations! You have successfully added Redis to your existing Helm chart. This integration allows your application to use Redis for caching, session management, and other use cases, managed efficiently with Helm. Customize the Redis configuration further by modifying the `values.yaml` file as needed. 🎉 # Environment Variables Source: https://docs.localops.co/bring-your-helm-charts/env-vars You can dynamically configure your application by passing environment variables to the container hosting your application image by adding them to the pod template specification in your Helm chart. ```yaml theme={null} apiVersion: apps/v1 kind: Deployment metadata: name: acme-api-deployment spec: replicas: 3 selector: matchLabels: app: acme-api template: metadata: labels: app: acme-api spec: containers: - name: api-container image: public.ecr.aws/ach42q1u/acme-api:1.0.0 ports: - containerPort: 8080 env: - name: APP_PORT value: '8080' - name: DB_USER value: '{{ .Values.db.user }}' - name: DB_PASS value: '{{ .Values.db.pass }}' - name: DB_HOST value: '{{ .Values.db.host }}' - name: DB_PORT value: '{{ .Values.db.port }}' ``` You can set the values for these environment variables directly, such as `APP_PORT` in this example. You can also use Helm values to customize your application's configuration for each environment you wish to create. ```yaml theme={null} db: host: postgres-service user: postgres pass: postgres port: 5432 ``` The environment variables `DB_USER`, `DB_PASS`, `DB_HOST`, and `DB_PORT` are set dynamically during each deployment. # I have a Docker Image Source: https://docs.localops.co/bring-your-helm-charts/first-steps/have-docker Now that you have your Docker images ready, we need to publish them to a registry and package them via Helm charts. If you don't have a Docker image, see the [I don't have a Docker image](/bring-your-helm-charts/first-steps/no-docker) section to create images. ## Prerequisites * [AWS account](https://aws.amazon.com/) * [Docker] to push the built images to AWS ECR. ## Publish Docker images to AWS ECR You can push your container images to an Amazon ECR repository with the `docker push` command. Before pushing the images, the Amazon ECR repository must exist. For more information, refer to the [AWS official guide](https://docs.aws.amazon.com/AmazonECR/latest/userguide/repository-create.html) for creating repositories. ## Authentication We must authenticate the Docker client to the Amazon ECR registry to which we want to push the image. Authentication should be done for each registry used, and the tokens are valid for 12 hours. To authenticate Docker to an Amazon ECR registry, run the `aws ecr get-login-password` command and then pass the authentication token to the `docker login` command. If you want to authenticate to multiple registries, you must repeat the command for each registry. ```shell theme={null} aws ecr get-login-password --region \ | docker login --username AWS \ --password-stdin .dkr.ecr..amazonaws.com ``` ## Manual build and push docker images ### Preparing the images Ideally, it is recommended to write a [Makefile](https://opensource.com/article/18/8/what-how-makefile) or any scripts to automate the following process. For convenience throughout the guide, let's export some environment variables to the shell, which we will be referring to in the commands we use. ```bash theme={null} export IMAGE_VERSION=0.0.1 \ APP_NAME=my-app \ AWS_ACC_NO=123456789012 \ ECR_REGION=us-east-1 \ ECR_REPO=my-app-repo ``` The following is an example reference of how to set environment variables in Windows and Linux and use them: > **Example to export environment variables in different Operating Systems** > > Export the variable to the shell: > > **Linux** > > ```bash theme={null} > bash export IMAGE_VERSION=1.0.0 APP_NAME=my-app > ``` > > **Windows (CMD)** > > ```powershell theme={null} > powershell set IMAGE_VERSION=1.0.0 && set APP_NAME=my-app > ``` > > **Windows (Powershell)** > > ```powershell theme={null} > powershell $env:IMAGE_VERSION="1.0.0"; $env:APP_NAME="my-app" > ``` > > Using the environment variable: > > **Linux** > > ```bash theme={null} > docker build -t $APP_NAME:$IMAGE_VERSION . > ``` > > **Windows (CMD)** > > ```powershell theme={null} > docker build -t %APP_NAME%:%IMAGE_VERSION% . > ``` > > **Windows (Powershell)** > > ```powershell theme={null} > docker build -t ${env:APP_NAME}:${env:IMAGE_VERSION} > ``` For simplicity's sake, we will be using Linux references throughout the guide. ### Building the image Use the [docker build](https://docs.docker.com/reference/cli/docker/buildx/build/) command to build the images and tag the image with your app name and version. ```bash theme={null} docker build \ --platform linux/amd64 \ -t $APP_NAME:$IMAGE_VERSION . ``` Now, you can check the tag we created using the command: ```bash theme={null} docker image ls ``` If your `APP_NAME` is `my-app` and `IMAGE_VERSION` is `v1.0.0`, it would print the following: ``` REPOSITORY TAG IMAGE ID CREATED SIZE my-app v1.0.0 4daf08897bf2 About a minute ago 136MB ``` ### Tagging the image Once the app is built, tag your image with the combination of the Amazon ECR registry, repository, and image tag to use. The registry format is `.dkr.ecr..amazonaws.com`. Run the following commands to create two tags: ```bash theme={null} docker tag $APP_NAME:$IMAGE_VERSION \ $AWS_ACC_NO.dkr.ecr.$ECR_REGION.amazonaws.com/$ECR_REPO:$IMAGE_VERSION ``` ```bash theme={null} docker tag $APP_NAME:$IMAGE_VERSION \ $AWS_ACC_NO.dkr.ecr.$ECR_REGION.amazonaws.com/$ECR_REPO:latest ``` > [!NOTE] > > The repository name should match the repository that you created for your image. We create two tags here since we use versioning. The first one is to tag the image with the version we have built, and the latter is to mark the recently pushed image as latest. The `latest` tag should always point to the recently pushed stable image. ### Push the image to ECR Once the images are tagged, push them to ECR by running the following commands: ```shell theme={null} docker push $AWS_ACC_NO.dkr.ecr.$ECR_REGION.amazonaws.com/$ECR_REPO:latest ``` ```shell theme={null} docker push $AWS_ACC_NO.dkr.ecr.$ECR_REGION.amazonaws.com/$ECR_REPO:$IMAGE_VERSION ``` You can find more information on publishing to AWS in their [official guide](https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-push-ecr-image.html). **Congratulations!🚀 You have successfully pushed your Docker image to an AWS ECR private repository.** ## Build and push docker images with Github Actions If you are using Github, you can use Github Actions to build and push your images to AWS ECR. Here is an example workflow: ```yaml theme={null} name: Push the Docker image to AWS ECR Repo on: push: tags: - v* jobs: Build: name: Build runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v2 - name: Configure AWS credentials uses: aws-actions/configure-aws-credentials@v1 with: aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }} aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }} aws-region: ap-south-1 - name: Login to Amazon ECR id: login-ecr uses: aws-actions/amazon-ecr-login@v1 - name: Build, tag, and push the image to Amazon ECR id: build-image env: ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }} ECR_REPOSITORY: ${{ secrets.REPO_NAME }} IMAGE_TAG: ${{ github.ref_name }} run: | docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG . docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG docker push $ECR_REGISTRY/$ECR_REPOSITORY:latest ``` or, If you want to push on every commit, you can use the following workflow: ```yaml theme={null} name: Push the Docker image to AWS ECR Repo on: push: branches: - main jobs: Build: runs-on: ubuntu-latest steps: # ... same upto Login to Amazon ECR - name: Get commit hash id: get-commit-hash run: echo "::set-output name=commit-hash::$(git rev-parse --short HEAD)" - name: Get timestamp id: get-timestamp run: echo "::set-output name=timestamp::$(date +'%Y-%m-%d-%H-%M')" - name: Build, tag, and push the image to Amazon ECR id: build-image env: ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }} ECR_REPOSITORY: ${{ secrets.REPO_NAME }} IMAGE_TAG: ${{ steps.get-commit-hash.outputs.commit-hash }}-${{ steps.get-timestamp.outputs.timestamp }} run: | docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG . docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG docker push $ECR_REGISTRY/$ECR_REPOSITORY:latest ``` These examples are provided for customization based on your specific use case. While the examples use long-term credentials for authentication, it is recommended to use OpenID Connect (OIDC) for enhanced security. For more information, refer to the guide on [Configuring OpenID Connect in Amazon Web Services](https://docs.github.com/en/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services). ## Prepare a Helm chart Helm is like a package manager for Kubernetes, which coordinates the download, installation, and deployment of apps. Helm charts are the way we can define an application as a collection of related Kubernetes resources. In LocalOps, packaging the application as Helm makes deployments, updates, and managing your application a breeze. You can refer to the [node-react](/bring-your-helm-charts/tutorials/node-react) app tutorial to see how to prepare a Helm chart for a Node.js application. You can also refer to other [tutorials](/bring-your-helm-charts/tutorials) for references to create your Helm chart. ## Package a Helm chart Once you have prepared your Helm chart, you need to package it. Packaging a Helm directory as a Helm chart involves creating a `.tgz` (tarball) file that contains your Helm chart. This file can then be easily shared, versioned, and deployed. Here are the steps to package your Helm chart: > [!NOTE] > > The below steps require the **Helm CLI** to be installed. If it is not already installed, please refer to [this > article](https://helm.sh/docs/intro/install/) for installation instructions. From the root of the Helm directory, run the following command: ```bash theme={null} helm package . -d .tmp ``` The above command will package the Helm chart into a file named `-.tgz`, which will be saved in the `.tmp` directory. [docker]: https://docs.docker.com/ # I have a docker compose setup Source: https://docs.localops.co/bring-your-helm-charts/first-steps/have-docker-compose Follow this guide to package your application as a Helm chart using the `docker-compose.yaml` file that you already have. We will use a simple example containing an application connected to a PostgreSQL database. ```yaml compose.yml theme={null} volumes: pg_app_data: services: example-app: image: public.aws.ecr//example-app:1.0.0 environment: DB_HOST: database DB_NAME: app_db DB_USER: postgres DB_PASS: postgres DB_PORT: 5432 APP_PORT: 8000 ports: - '8000:8000' depends_on: - database database: image: postgres:14.8-alpine3.18 environment: POSTGRES_DB: app_db POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres volumes: - pg_app_data:/var/lib/postgresql/data ports: - '5432:5432' ``` ## Create a Helm chart from your Docker Compose 1. Create a directory and set up the Helm Chart Directory Structure in it using the `helm create example-app-chart` command. 2. Write a deployment object (Kubernetes manifest) for each of the services from the `docker-compose.yaml` file, in the templates directory. They define the desired state for application pods, ensuring that the specified number of replicas of the application is running at any given time. ```yaml templates/deployments.yaml theme={null} apiVersion: apps/v1 kind: StatefulSet metadata: name: postgres-statefulset spec: serviceName: '{{ .Values.db.host }}' replicas: 1 selector: matchLabels: app: postgres-db template: metadata: labels: app: postgres-db spec: containers: - name: postgres-container image: postgres:14.8-alpine3.18 env: - name: POSTGRES_DB value: '{{ .Values.db.name }}' - name: POSTGRES_USER value: '{{ .Values.db.user }}' - name: POSTGRES_PASSWORD value: '{{ .Values.db.pass }}' - name: PGDATA value: /var/lib/postgresql/data/todo/ ports: - containerPort: { { .Values.db.port } } volumeMounts: - name: postgres-storage mountPath: /var/lib/postgresql/data --- apiVersion: apps/v1 kind: Deployment metadata: name: example-app-deployment spec: replicas: { { .Values.replicaCount } } selector: matchLabels: app: example-app template: metadata: labels: app: example-app spec: containers: - name: example-app-container image: '{{ .Values.example-app.image }}:{{ .Values.example-app.imageVersion }}' env: - name: DB_HOST value: '{{ .Values.db.host }}' - name: DB_PORT value: '{{ .Values.db.port }}' - name: DB_NAME value: '{{ .Values.db.name }}' - name: DB_USER value: '{{ .Values.db.user }}' - name: DB_PASS value: '{{ .Values.db.pass }}' - name: HELM_VERSION value: '{{ .Chart.Version }}' - name: APP_PORT value: '{{ .Values.example-app.service.port }}' ports: containerPort: { { .Values.example-app.service.port } } initContainers: - name: check-db-ready image: postgres:14.8-alpine3.18 env: - name: POSTGRES_HOST value: '{{ .Values.db.host }}' - name: POSTGRES_PORT value: '{{ .Values.db.port }}' command: [ 'sh', '-c', 'echo Checking if postgres is up; until pg_isready -h $POSTGRES_HOST -p $POSTGRES_PORT; do echo Waiting for postgres database to be up...; sleep 2; done; echo Postgres is up!', ] ``` > [!NOTE] > > We can see that example-app service depends on the database service in the docker-compose file. The depends\_on field > from Docker Compose, which defines dependencies between services, can be mimicked using initContainers in a Deployment > object. initContainers run to completion before the main application containers start. They can be used to ensure that > a dependent service is ready before starting the main application. 3. Write a service object (kubernetes manifest) for each of the services from docker-compose.yaml file, in the templates directory, to expose the ports your services run on accordingly. ```yaml templates/services.yaml theme={null} apiVersion: v1 kind: Service metadata: name: example-app-service spec: type: { { .Values.example-app.service.type } } selector: app: example-app ports: - protocol: TCP port: { { .Values.example-app.service.port } } targetPort: { { .Values.example-app.service.targetPort } } --- apiVersion: v1 kind: Service metadata: name: postgres-service spec: selector: app: postgres-db ports: - protocol: TCP port: 5432 ``` > [!NOTE] > > The service.type field specifies how a service is exposed. Learn more about [service types and their > values](https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services-service-types) 4. Create values.yaml file with appropriate values required by your helm chart ```yaml values.yaml theme={null} replicaCount: 1 example-app: service: type: NodePort port: 8000 targetPort: 8000 image: public.ecr.aws//example-app imageVersion: 1.0.0 db: host: postgres-service port: 5432 name: app_db user: postgres pass: postgres ``` 5. Now that you've created a helm chart using your Docker Compose follow this guide to publish your helm chart and get it deployed in a Localops application environment. ## Next Steps * [Publishing your Helm charts](/bring-your-helm-charts/publish/ecr) * [Creating an app](https://help.localops.co/en/articles/9580323-apps) * [Creating a release](https://help.localops.co/en/articles/9582027-releases) * [Deploy 🚀](https://help.localops.co/en/articles/9582075-app-environments) # I have a Helm Chart Source: https://docs.localops.co/bring-your-helm-charts/first-steps/have-helm Awesome! You have everything you need to get your deployments running. The next step is to publish your Helm chart. Check out [this guide](/bring-your-helm-charts/publish/ecr) to publish your Helm chart to Amazon ECR (Elastic Container Registry). > [!NOTE] > > LocalOps currently can access Helm charts stored in Amazon ECR. Support for other registries will be coming soon. Once you finish publishing your Helm chart, follow these steps: 1. Create an [App](https://help.localops.co/en/articles/9580323-apps). 2. Create a [Release](https://help.localops.co/en/articles/9582027-releases) for each version of your Helm chart that you wish to deploy. 3. Create a [Cloud Connection](/accounts/aws) to the target cloud account where you would like to create your app environments. 4. Select the desired connection, specific application, release version, and the environment template to be applied, then proceed to create an [environment](https://help.localops.co/en/articles/9582075-app-environments). That's it. # I don't have a Docker Image Source: https://docs.localops.co/bring-your-helm-charts/first-steps/no-docker You are here because your awesome app is ready and now it's time to package it. ## Prerequisites * Your app * [Docker] to build standalone images to serve your production app. ## Getting Started Dockerizing your app ensures consistency, portability, isolation, and several other benefits. If you haven't installed Docker already, you can find the installation instructions for various operating systems in the [official docs](https://docs.docker.com/engine/install/). Let's create a simple Node.js script that runs an HTTP server on port `3000` and when the URL `/` is hit, it prints `Hello World!` ```js app.js theme={null} const express = require('express'); const app = express(); const port = process.env.PORT ?? 3000; app.get('/', (req, res) => { res.send('Hello World!'); }); app.listen(port, () => { console.log(`Example app listening on port ${port}`); }); ``` We can run this app by running the following command: ```bash theme={null} node app.js ``` That's it, we have our Node.js app running. ## Writing the Dockerfile Now, let's create a Dockerfile for the above app. A `Dockerfile` is a set of instructions that tells Docker how to get our app working in our environment. ```docker Dockerfile theme={null} # Use the official Node.js image with version 20 based on Alpine Linux # Alpine images are smaller in size hence preferred FROM node:20-alpine # Set environment variable for the application's port # this is used in app.js ENV PORT=3000 # Set env to production to tell app and other tools that the app is running in production mode # will be useful to disable debugging logs, skip few things etc., ENV NODE_ENV=production # Set the working directory inside the container to /app # this will be the root context of our app, # we will be copying and running script from inside this folder WORKDIR /app # Copy package.json and package-lock.json to the working directory COPY package.json package-lock.json* ./ # Install dependencies specified in package-lock.json # using npm ci for a clean install RUN npm ci # Copy the rest of the application files to the working directory # while copying this respects the contents given in dockerignore COPY . . # Expose the application port to be accessible from outside the container EXPOSE ${PORT} # Start the application CMD ["node", "app.js"] ``` As you can see, the Dockerfile is a set of instructions that automate the steps you would take manually to get the app running on your machine. Though Docker supports [Multi-Stage Builds](https://docs.docker.com/build/building/multi-stage/), we won't be using that here since Node.js needs all the source code and `node_modules` to be present while running the application. Prefer to opt-in for multistage builds whenever possible. > [!NOTE] > > In real-world scenarios, you might have more than just an HTTP server. You might have other services running > parallelly too, like schedulers, workers, notification services, gateways, etc,. You'll need to create a Dockerfile for > each and link them while creating the Helm charts. > > You might also choose to run everything in the same container, which is mostly not recommended, since you might lose > isolation, scalability, etc. > [!TIP] > > It is heavily recommended to have a `.dockerignore` file to ignore certain prebuilt binaries and non-project-related > stuff being copied from our local to the Docker container. Read more on [.dockerignore here](https://docs.docker.com/build/building/context/#dockerignore-files). An example ignore file: ```ignore .dockerignore theme={null} Dockerfile .dockerignore node_modules npm-debug.log README.md .git ``` It is essential to ignore folders like `node_modules` since when installing dependencies, few libraries might build binaries depending on your platform. We don't want them to be copied since it might replace the binaries built inside the container itself while running `npm ci`, causing the application to break or misbehave. ## Examples for Dockerfiles for Other Languages > **GoLang** > > You can put any content in here, including other components, like code: > > This Dockerfile uses a multistage build to compile a Go application in a Golang builder image and then runs it in a > lightweight Alpine image, ensuring a minimal final image size. > > ```docker Dockerfile theme={null} > # Stage 1: Build the Go application > FROM golang:1.18 as builder > > # Set the working directory inside the container > WORKDIR /app > > # Copy the Go module files and download dependencies > COPY go.mod go.sum ./ > RUN go mod download > > # Copy the rest of the application code > COPY . . > > # Build the Go application > RUN go build -o main . > > # Stage 2: Create a lightweight container to run the Go application > FROM alpine:latest > > # Set the working directory inside the container > WORKDIR /root/ > > # Copy the Go binary from the builder stage > COPY --from=builder /app/main . > > # Expose the application port > EXPOSE 8080 > > # Command to run the Go application > CMD ["./main"] > ``` > > A `.dockerignore` file for reference: > > ```ignore theme={null} > # Ignore Go build artifacts > main > *.o > *.a > *.so > *.out > # Ignore other unnecessary files > .git > .gitignore > Dockerfile > docker-compose.yml > ``` > **Django (Python)** > > This Dockerfile installs Django dependencies in one stage and then copies the dependencies and application code to a > slim Python image, optimizing the final container size and performance. > > ```docker Dockerfile theme={null} > # Stage 1: Install dependencies > FROM python:3.10-slim as builder > > # Set the working directory inside the container > WORKDIR /app > > # Copy the requirements file and install dependencies > COPY requirements.txt . > RUN pip install --no-cache-dir -r requirements.txt > > # Copy the rest of the application code > COPY . . > > # Stage 2: Create a lightweight container to run the Django application > FROM python:3.10-slim > > # Set the working directory inside the container > WORKDIR /app > > # Copy the installed dependencies and application code from the builder stage > COPY --from=builder /app /app > > # Expose the application port > EXPOSE 8000 > > # Command to run the Django application > CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"] > ``` > > A `.dockerignore` file for reference: > > ```ignore theme={null} > # Ignore Python bytecode files > *.pyc > *.pyo > __pycache__ > # Ignore other unnecessary files > .git > .gitignore > Dockerfile > docker-compose.yml > # Ignore local Django settings > local_settings.py > db.sqlite3 > ``` > **Ruby on Rails** > > This Dockerfile leverages a multistage build to install Ruby and system dependencies, precompile assets in a Ruby > builder image, and then run the Rails application in a slimmer Ruby image, reducing the overall image size. > > ```docker title='Dockerfile' theme={null} > # Stage 1: Build the Rails application > FROM ruby:3.1 as builder > > # Set the working directory inside the container > WORKDIR /app > > # Copy the Gemfile and Gemfile.lock and install dependencies > COPY Gemfile Gemfile.lock ./ > RUN bundle install > > # Copy the rest of the application code > COPY . . > > # Precompile the Rails assets > RUN bundle exec rake assets:precompile > > # Stage 2: Create a lightweight container to run the Rails application > FROM ruby:3.1-slim > > # Set the working directory inside the container > WORKDIR /app > > # Copy the installed dependencies and application code from the builder stage > COPY --from=builder /app /app > > # Install system dependencies for Rails > RUN apt-get update && apt-get install -y nodejs > > # Expose the application port > EXPOSE 3000 > > # Command to run the Rails application > CMD ["rails", "server", "-b", "0.0.0.0"] > ``` > > A `.dockerignore` file for reference: > > ```ignore theme={null} > # Ignore Ruby build artifacts > *.gem > *.rbc > # Ignore other unnecessary files > .git > .gitignore > Dockerfile > docker-compose.yml > # Ignore local Rails settings > config/database.yml > db/*.sqlite3 > log/* > tmp/* > ``` > [!NOTE] > > All these Dockerfiles are references to how you might package the application; actual steps might vary depending on > the application you build and the features you use. ## Building Images To build your Docker image, use the following command in the directory containing your Dockerfile: ```bash theme={null} docker build --platform linux/amd64 -t node-app:latest . ``` This command builds the `node-app` image for `platform linux/amd64` and tags it as `latest`. If you are locally testing your application, you can skip the `platform` key to build the images ```bash theme={null} # only for testing in local machine docker build -t node-app:latest . ``` ## Running Your Docker Image Now, we have images, its time run the image. Use the following command: ```bash theme={null} docker run \ -it \ --rm \ --name node-app \ -e PORT=3000 \ -d \ -p 3000:3000 \ node-app ``` * `-it`: enables interactivity with TTY * `--rm`: to tell the Docker Daemon to clean up the container and remove the file system after the container exits * `--name node-app`: Name of the container `node-app`. * `-e PORT=3000`: Sets the environment variable PORT in docker `3000`. * `-d`: Runs the container in detached(background) mode. You can skip the flag to see the logs directly in your terminal window. * `-p 3000:3000`: Maps port 3000 on your host to port 3000 in the container. * `node-app` in the end is the name of the image This command runs your Docker image, mapping port `3000` of the container to port `3000` on your local machine. Once the service is up, visit `http://localhost:3000` to see the app we built running. Hurray 🎉. Now we have package our app for production use using docker. ## Next Steps Once the docker is ready, the next steps will be * [Publishing the docker images](/bring-your-helm-charts/first-steps/have-docker#publish-docker-images-to-aws-ecr) * [Packaging the app with helm](/bring-your-helm-charts/first-steps/have-docker#package-a-helm-chart) * [Publishing your Helm charts](/bring-your-helm-charts/publish/ecr) * [Creating app](https://help.localops.co/en/articles/9580323-apps) * [Creating release](https://help.localops.co/en/articles/9582027-releases) * [Deploy 🚀](https://help.localops.co/en/articles/9582075-app-environments) [docker]: https://docs.docker.com/ # Multiple Helm Charts Source: https://docs.localops.co/bring-your-helm-charts/multiple-helm-charts In complex application environments, managing multiple Helm charts individually can become cumbersome. Consolidating multiple Helm charts into a single Helm chart allows for easier management, deployment, and versioning of your application components. This guide outlines the steps to bring multiple Helm charts into an App Helm chart. ## Why Consolidate Helm Charts? Bringing multiple Helm charts into a single App Helm chart offers several benefits: * **Simplified Management**: Manage all application components (services, deployments, configurations) under one umbrella. * **Improved Deployment**: Deploying a single Helm chart simplifies deployment workflows and ensures consistency. * **Version Control**: Maintain version control for all components within the same repository or package. * **Easier Collaboration**: Facilitates collaboration among team members working on different components of the application. ## Steps to Bring Multiple Helm Charts into an App Helm Chart ### 1. Understand Dependencies and Interactions Before consolidating Helm charts, it's crucial to understand dependencies and interactions between different components of your application. Identify Helm charts for each component (e.g., frontend, backend, database) and their interdependencies. ### 2. Create a New App Helm Chart Structure Start by creating a new directory structure for your App Helm chart. This directory will serve as the root directory containing subdirectories for each Helm chart you intend to include. ```plaintext theme={null} app-chart/ ├── Chart.yaml # Main Chart metadata ├── values.yaml # Main Chart default values ├── charts/ │ ├── frontend/ # Subchart for frontend component │ │ ├── Chart.yaml │ │ ├── templates/ │ │ │ └── ... │ │ └── ... │ ├── backend/ # Subchart for backend component │ │ ├── Chart.yaml │ │ ├── templates/ │ │ │ └── ... │ │ └── ... │ └── database/ # Subchart for database component │ ├── Chart.yaml │ ├── templates/ │ │ └── ... │ └── ... └── ... ``` ### 3. Include Subcharts in the Main Chart Edit the `Chart.yaml` file of your main App Helm chart to define dependencies on each subchart (frontend, backend, database). Specify the versions and configurations required for each subchart. ```yaml app-chart/Chart.yaml theme={null} apiVersion: v2 name: app-chart description: Main Helm chart for the entire application version: 0.1.0 appVersion: '1.0' dependencies: - name: frontend version: '1.0.0' repository: 'file://./charts/frontend' - name: backend version: '1.0.0' repository: 'file://./charts/backend' - name: database version: '1.0.0' repository: 'file://./charts/database' ``` ### 4. Customize Values and Templates Modify the `values.yaml` and templates within each subchart (`charts/frontend/values.yaml`, etc.) to align with your application's specific configuration requirements. Ensure that values and configurations are correctly propagated from the main chart to the subcharts. ### 5. Test and Deploy Before deploying to production, test your consolidated Helm chart in a development or staging environment. Validate that all components deploy as expected and that configurations are applied correctly across all subcharts. > [!TIP] > > Update and Version Control > > As you make updates to individual components (frontend, backend, database), update the corresponding subcharts within > your main App Helm chart (`app-chart/charts/frontend`, etc.). Use version control to manage changes and track versions > effectively. # Publish helm chart to ECR Source: https://docs.localops.co/bring-your-helm-charts/publish/ecr > [!NOTE] > > This article assumes that you have helm chart for your application. Publishing a Helm package to an AWS ECR *(Elastic Container Registry)* private repository involves several steps: 1. [Package the Helm chart](/bring-your-helm-charts/first-steps/have-docker#package-a-helm-chart) 2. [Create an ECR private repository](#2-create-an-ecr-private-repository) 3. [Authenticate Helm to your ECR private registry](#3-authenticate-helm-to-your-ecr-private-registry) 4. [Push the Helm chart to ECR private registry](#4-push-the-helm-chart-to-ecr-private-registry) ### 1. Package as Helm chart To package as helm chart please refer [this article](/bring-your-helm-charts/first-steps/have-docker#package-a-helm-chart). ### 2. Create an ECR private repository 1. Login to [AWS console](https://console.aws.amazon.com). 2. Go to [ECR console](https://console.aws.amazon.com/ecr). 3. Switch to the preferred AWS region where you want to create the ECR private repository. 4. Create a private repository, 1. In the left navigation pane, click on [**Private registry -> Repositories**](https://console.aws.amazon.com/ecr/private-registry/repositories). 2. Click on the **Create repository** button. 3. Fill in repository name field.\ Repository name must be same as Helm chart name. You can find your Helm chart name in **Chart.yaml -> name**. 4. Click on **Create repository** button. ### 3. Authenticate Helm to your ECR private registry > [!NOTE] > > Below steps require the **AWS CLI** to be installed and setup with required credentials. If it is not already installed, > please refer to > [this article](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html#getting-started-install-instructions) > for installation instructions. > > Below steps require the **Helm CLI** to be installed. If it is not already installed, please refer to > [this article](https://helm.sh/docs/intro/install/) for installation instructions. * Login to ECR private helm registry, ```shell theme={null} aws ecr get-login-password \ --region | helm registry login \ --username AWS \ --password-stdin .dkr.ecr..amazonaws.com ``` Above command should output, ```shell theme={null} Login Succeeded ``` ### 4. Push the Helm chart to ECR private registry * Below command will push the packaged helm chart to your ECR private registry, ```shell theme={null} helm push -.tgz oci://.dkr.ecr..amazonaws.com/ ``` * You can optionally verify the Helm push by navigating to your [**ECR -> Private registry -> Repositories**](https://console.aws.amazon.com/ecr/private-registry/repositories) in your AWS console. # Go + React Source: https://docs.localops.co/bring-your-helm-charts/tutorials/go-react In this tutorial, we will integrate a backend (Go) app with a frontend (React.js) app by preparing a Helm chart. ## Prerequisites * [Docker] to build standalone containers to serve your production app. * [Helm] package that contains all the resources you need to deploy an application to a [Kubernetes] cluster. * [Minikube] to set up Kubernetes clusters locally. > [!NOTE] > > This guide assumes that you have basic knowledge of the above-mentioned technologies and tools. If you are not > familiar with any of them, it is highly recommended to review their official documentation and tutorials to get up to > speed before proceeding with this guide. > > By this time, it is assumed that you have a backend with Go and a frontend application, both dockerized and published to > a registry. If not, check out these guides to get you started before proceeding further: * [Building and packaging a Go app](/guides/languages/go) * [Building and packaging a React app](/guides/spa/react) * [Publishing Docker images to a registry](/bring-your-helm-charts/first-steps/have-docker#push-the-image-to-ecr) ## Setup Minikube [Minikube] is local Kubernetes, focusing on making it easy to learn and develop for Kubernetes. Refer to the [installation guide](https://minikube.sigs.k8s.io/docs/start) for installing Minikube on your machine. Since we are building and testing the images locally, you might have built the [react-app](/guides/spa/react) and [go-app](/guides/languages/go) already. In short, run these commands from the root of the respective project to build the images: ```bash theme={null} # Build the frontend (react-app) Docker image docker build -t react-app:latest . # Build the backend (go-app) Docker image docker build -t go-app:latest . ``` Once the images are built, we need to load them into Minikube: ```bash theme={null} # Load the images into Minikube minikube image load react-app:latest minikube image load go-app:latest ``` The above command takes the mentioned image that is available as an archive and makes it available in the cluster. ## Create Helm Chart For this guide, we'll create a simple chart called `go-react-chart`, and then we'll create some templates inside of the chart. ```bash theme={null} helm create go-react-chart ``` Once the chart is created, it will have some default templates. We don't need them for now. Let's copy them to another folder called `templates-bak`. You might need them later for reference or you can remove them. ```bash theme={null} mv go-react-chart/templates go-react-chart/templates-bak ``` :::tip When you're writing production-grade charts, having basic versions of these charts can be really useful. So in your day-to-day chart authoring, you probably won't want to remove them. ::: Now, create a templates directory for us to write new templates. ```bash theme={null} cd go-react-chart mkdir templates ``` ### Create/Modify `values.yaml` Assume that you have built the images locally. You might have a `values.yaml` file in the root directory created by Helm with sample content. Let's clear the contents and update them with the following to specify the images and the tag to be used for deployments. ```yaml title='values.yaml' theme={null} frontend: image: repository: react-app tag: latest env: PORT: 80 backend: image: repository: go-app tag: latest env: PORT: 8000 gateway: port: 80 service: type: NodePort image: # using the alpine version of Nginx to reduce bundle size repository: nginx tag: alpine ``` > [!NOTE] > > Here we are using the locally built images for testing. In a real app scenario, the repository will be replaced with > the actual registry URL depending on where it is published. For example, if your app is published in public AWS ECR, the input will be like: ```yaml theme={null} frontend: image: repository: public.aws.ecr//react-app tag: latest # or the explicit version tag: v1.0.0 ``` ### Create Deployments/Kubernetes Manifests Now let's create deployments for all three services: * **frontend** - a React app * **backend** - a Go app * **gateway** - an Nginx server to route traffic to the frontend and backend depending on the URL path #### Frontend Deployment Let's create a manifest that will create a deployment for the frontend application, specifying the Docker image and setting the `PORT` environment variable. It also creates a service to expose the frontend application. ```yaml templates/frontend.yaml theme={null} apiVersion: apps/v1 kind: Deployment metadata: name: frontend spec: replicas: 1 selector: matchLabels: app: frontend template: metadata: labels: app: frontend spec: containers: - name: frontend image: '{{ .Values.frontend.image.repository }}:{{ .Values.frontend.image.tag }}' # set the imagePullPolicy only while testing local images # skip this while using registry images imagePullPolicy: IfNotPresent ports: - containerPort: { { .Values.frontend.env.PORT } } env: - name: PORT value: '{{ .Values.frontend.env.PORT }}' --- apiVersion: v1 kind: Service metadata: name: frontend spec: selector: app: frontend ports: - protocol: TCP port: { { .Values.frontend.env.PORT } } targetPort: { { .Values.frontend.env.PORT } } ``` #### Backend Deployment Create another manifest that will create a deployment for the backend application, specifying the Docker image and setting the `PORT` environment variable. It also creates a service to expose the backend application. ```yaml templates/backend.yaml theme={null} apiVersion: apps/v1 kind: Deployment metadata: name: backend spec: replicas: 1 selector: matchLabels: app: backend template: metadata: labels: app: backend spec: containers: - name: backend image: '{{ .Values.backend.image.repository }}:{{ .Values.backend.image.tag }}' # set the imagePullPolicy only while testing local images # skip this while using registry images imagePullPolicy: IfNotPresent ports: - containerPort: { { .Values.backend.env.PORT } } env: - name: PORT value: '{{ .Values.backend.env.PORT }}' --- apiVersion: v1 kind: Service metadata: name: backend spec: selector: app: backend ports: - protocol: TCP port: { { .Values.backend.env.PORT } } targetPort: { { .Values.backend.env.PORT } } ``` #### Gateway Deployment We need one more manifest, which will create a deployment for the Nginx gateway. This gateway service will route traffic to the frontend and backend services based on the request path. It also creates a service to expose the gateway. ```yaml templates/gateway.yaml theme={null} apiVersion: apps/v1 kind: Deployment metadata: name: gateway spec: replicas: 1 selector: matchLabels: app: gateway template: metadata: labels: app: gateway spec: containers: - name: gateway image: '{{ .Values.gateway.image.repository }}:{{ .Values.gateway.image.tag }}' ports: - containerPort: { { .Values.gateway.port } } volumeMounts: - name: nginx-config mountPath: /etc/nginx/nginx.conf subPath: nginx.conf volumes: - name: nginx-config configMap: name: nginx-config --- apiVersion: v1 kind: Service metadata: name: gateway spec: type: { { .Values.gateway.service.type } } selector: app: gateway ports: - protocol: TCP port: { { .Values.gateway.port } } targetPort: { { .Values.gateway.port } } ``` #### Nginx ConfigMap This ConfigMap defines the Nginx configuration, specifying the routing rules to direct traffic to the appropriate service based on the request path. ```yaml templates/nginx-config.yaml theme={null} apiVersion: v1 kind: ConfigMap metadata: name: nginx-config data: nginx.conf: | events { } http { upstream frontend { server frontend:{{ .Values.frontend.env.PORT }}; } upstream backend { server backend:{{ .Values.backend.env.PORT }}; } server { listen {{ .Values.gateway.port }}; location / { proxy_pass http://frontend; } location /api/ { rewrite ^/api/(.*) /$1 break; proxy_pass http://backend; } } } ``` Hurray 🎉! Now we have the chart ready. Next is to install and run the app in the local Kubernetes cluster. ## Install the Chart To install the services, run the following from the root of the chart directory: ```bash theme={null} helm install go-react . ``` > [!TIP] > > The `helm install` command would pick the values from `values.yaml` and spin up the cluster. Alternatively, you > can create another file called \`local-values > > .yaml`which contains the local images, and`values.yaml\` can have actual default values. To use another YAML file instead of the default `values.yaml` for local development, run: ```bash theme={null} helm install -f local-values.yaml go-react . ``` If the installation is successful, you would see the following in your terminal output: ```text theme={null} NAME: go-react LAST DEPLOYED: NAMESPACE: default STATUS: deployed REVISION: 1 TEST SUITE: None ``` This will bring up 3 pods for each service/deployment we created. Run the following command to see the list of pods running: ```bash theme={null} watch -n 2 kubectl get all ``` You should see the following in your terminal: ```text theme={null} NAME READY STATUS RESTARTS AGE pod/backend-587b6668c5-fdgkt 1/1 Running 0 2m8s pod/frontend-84c4bb6dd6-n79f8 1/1 Running 0 2m8s pod/gateway-5b4bb95966-w9g7k 1/1 Running 0 2m8s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/backend ClusterIP 10.101.127.13 8000/TCP 2m8s service/frontend ClusterIP 10.106.145.105 80/TCP 2m8s service/gateway NodePort 10.97.166.143 80:31517/TCP 2m8s service/kubernetes ClusterIP 10.96.0.1 443/TCP 43h NAME READY UP-TO-DATE AVAILABLE AGE deployment.apps/backend 1/1 1 1 2m8s deployment.apps/frontend 1/1 1 1 2m8s deployment.apps/gateway 1/1 1 1 2m8s NAME DESIRED CURRENT READY AGE replicaset.apps/backend-587b6668c5 1 1 1 2m8s replicaset.apps/frontend-84c4bb6dd6 1 1 1 2m8s replicaset.apps/gateway-5b4bb95966 1 1 1 2m8s ``` To get the URL of the gateway service, run: ```bash theme={null} minikube service gateway --url ``` It would print the URL. Now you can access the: * Frontend at `http://127.0.0.1:/` * Backend at `http://127.0.0.1:/api/` #### Alternatively, you could also use Minikube tunnel to view the app. Change the `gateway.service.type` in the gateway from `NodePort` to `LoadBalancer`: ```yaml theme={null} gateway: port: 4000 service: type: LoadBalancer ``` and run: ```bash theme={null} minikube tunnel ``` Now you can access the: * Frontend at `http://localhost:4000/` * Backend at `http://localhost:4000/api/` > [!WARNING] > > LoadBalancer should be used only for development purposes. While pushing Helm charts to production for use with > LocalOps, use `NodePort`. ## Uninstalling the Helm App To clean up the app, run the following: ```bash theme={null} helm uninstall go-react minikube stop # to stop the Minikube ``` ## Before Publishing to Helm Registry > [!NOTE] > > Remove the `imagePullPolicy: IfNotPresent` from the deployment scripts. This is needed only to test the local images. > > Replace the repository in your `values.yaml` with actual registry images or use the custom YAML via the `-f` flag in the > Helm CLI. ## Next Steps Now we have the chart ready. The next steps would be: * [Publishing your Helm charts](/bring-your-helm-charts/publish/ecr) * [Creating an app](https://help.localops.co/en/articles/9580323-apps) * [Creating a release](https://help.localops.co/en/articles/9582027-releases) * [Deploy 🚀](https://help.localops.co/en/articles/9582075-app-environments) [Docker]: https://docs.docker.com/ [Helm]: https://helm.sh/ [Minikube]: https://minikube.sigs.k8s.io/docs/ [Kubernetes]: https://kubernetes.io/ # NodeJs + React Source: https://docs.localops.co/bring-your-helm-charts/tutorials/node-react In this tutorial, we will integrate a backend (Node.js + Express) app with a frontend (React.js) app by preparing a Helm chart. ## Prerequisites * [Docker] to build standalone containers to serve your production app. * [Helm] package that contains all the resources you need to deploy an application to a [Kubernetes] cluster. * [Minikube] to set up Kubernetes clusters locally. > [!NOTE] > > This guide assumes that you have basic knowledge of the above-mentioned technologies and tools. If you are not > familiar with any of them, it is highly recommended to review their official documentation and tutorials to get up to > speed before proceeding with this guide. > > By this time, it is assumed that you have a backend with Node.js and a frontend application, both dockerized and > published to a registry. If not, check out these guides to get you started before proceeding further: * [Building and packaging a Node.js app](/guides/languages/node) * [Building and packaging a React app](/guides/spa/react) * [Publishing Docker images to a registry](/bring-your-helm-charts/first-steps/have-docker#push-the-image-to-ecr) ## Setup Minikube [Minikube] is local Kubernetes, focusing on making it easy to learn and develop for Kubernetes. Refer to the [installation guide](https://minikube.sigs.k8s.io/docs/start) for installing Minikube on your machine. Since we are building and testing the images locally, you might have built the [react-app](/guides/spa/react) and [node-app](/guides/languages/node) already. In short, run these commands from the root of the respective project to build the images: ```bash theme={null} # Build the frontend (react-app) Docker image docker build -t react-app:latest . # Build the backend (node-app) Docker image docker build -t node-app:latest . ``` Once the images are built, we need to load them into Minikube: ```bash theme={null} # Load the images into Minikube minikube image load react-app:latest minikube image load node-app:latest ``` The above command takes the mentioned image that is available as an archive and makes it available in the cluster. ## Create Helm Chart For this guide, we'll create a simple chart called `node-react-chart`, and then we'll create some templates inside of the chart. ```bash theme={null} helm create node-react-chart ``` Once the chart is created, it will have some default templates. We don't need them for now. Let's copy them to another folder called `templates-bak`. You might need them later for reference or you can remove them. ```bash theme={null} mv node-react-chart/templates node-react-chart/templates-bak ``` :::tip When you're writing production-grade charts, having basic versions of these charts can be really useful. So in your day-to-day chart authoring, you probably won't want to remove them. ::: Now, create a templates directory for us to write new templates. ```bash theme={null} cd node-react-chart mkdir templates ``` ### Create/Modify `values.yaml` Assume that you have built the images locally. You might have a `values.yaml` file in the root directory created by Helm with sample content. Let's clear the contents and update them with the following to specify the images and the tag to be used for deployments. ```yaml values.yaml theme={null} frontend: image: repository: react-app tag: latest env: PORT: 80 backend: image: repository: node-app tag: latest env: PORT: 3000 gateway: port: 80 service: type: NodePort image: # using the alpine version of Nginx to reduce bundle size repository: nginx tag: alpine ``` > [!NOTE] > > Here we are using the locally built images for testing. In a real app scenario, the repository will be replaced with > the actual registry URL depending on where it is published. For example, if your app is published in public AWS ECR, the input will be like: ```yaml theme={null} frontend: image: repository: public.aws.ecr//react-app tag: latest # or the explicit version tag: v1.0.0 ``` ### Create Deployments/Kubernetes Manifests Now let's create deployments for all three services: * **frontend** - a React app * **backend** - a Node app * **gateway** - an Nginx server to route traffic to the frontend and backend depending on the URL path #### Frontend Deployment Let's create a manifest that will create a deployment for the frontend application, specifying the Docker image and setting the `PORT` environment variable. It also creates a service to expose the frontend application. ```yaml templates/frontend.yaml theme={null} apiVersion: apps/v1 kind: Deployment metadata: name: frontend spec: replicas: 1 selector: matchLabels: app: frontend template: metadata: labels: app: frontend spec: containers: - name: frontend image: '{{ .Values.frontend.image.repository }}:{{ .Values.frontend.image.tag }}' # set the imagePullPolicy only while testing local images # skip this while using registry images imagePullPolicy: IfNotPresent ports: - containerPort: { { .Values.frontend.env.PORT } } env: - name: PORT value: '{{ .Values.frontend.env.PORT }}' --- apiVersion: v1 kind: Service metadata: name: frontend spec: selector: app: frontend ports: - protocol: TCP port: { { .Values.frontend.env.PORT } } targetPort: { { .Values.frontend.env.PORT } } ``` #### Backend Deployment Create another manifest that will create a deployment for the backend application, specifying the Docker image and setting the `PORT` environment variable. It also creates a service to expose the backend application. ```yaml templates/backend.yaml theme={null} apiVersion: apps/v1 kind: Deployment metadata: name: backend spec: replicas: 1 selector: matchLabels: app: backend template: metadata: labels: app: backend spec: containers: - name: backend image: '{{ .Values.backend.image.repository }}:{{ .Values.backend.image.tag }}' # set the imagePullPolicy only while testing local images # skip this while using registry images imagePullPolicy: IfNotPresent ports: - containerPort: { { .Values.backend.env.PORT } } env: - name: PORT value: '{{ .Values.backend.env.PORT }}' --- apiVersion: v1 kind: Service metadata: name: backend spec: selector: app: backend ports: - protocol: TCP port: { { .Values.backend.env.PORT } } targetPort: { { .Values.backend.env.PORT } } ``` #### Gateway Deployment We need one more manifest, which will create a deployment for the Nginx gateway. This gateway service will route traffic to the frontend and backend services based on the request path. It also creates a service to expose the gateway. ```yaml templates/gateway.yaml theme={null} apiVersion: apps/v1 kind: Deployment metadata: name: gateway spec: replicas: 1 selector: matchLabels: app: gateway template: metadata: labels: app: gateway spec: containers: - name: gateway image: '{{ .Values.gateway.image.repository }}:{{ .Values.gateway.image.tag }}' ports: - containerPort: { { .Values.gateway.port } } volumeMounts: - name: nginx-config mountPath: /etc/nginx/nginx.conf subPath: nginx.conf volumes: - name: nginx-config configMap: name: nginx-config --- apiVersion: v1 kind: Service metadata: name: gateway spec: type: { { .Values.gateway.service.type } } selector: app: gateway ports: - protocol: TCP port: { { .Values.gateway.port } } targetPort: { { .Values.gateway.port } } ``` #### Nginx ConfigMap This ConfigMap defines the Nginx configuration, specifying the routing rules to direct traffic to the appropriate service based on the request path. ```yaml templates/nginx-config.yaml theme={null} apiVersion: v1 kind: ConfigMap metadata: name: nginx-config data: nginx.conf: | events { } http { upstream frontend { server frontend:{{ .Values.frontend.env.PORT }}; } upstream backend { server backend:{{ .Values.backend.env.PORT }}; } server { listen {{ .Values.gateway.port }}; location / { proxy_pass http://frontend; } location /api/ { rewrite ^/api/(.*) /$1 break; proxy_pass http://backend; } } } ``` Hurray 🎉! Now we have the chart ready. Next is to install and run the app in the local Kubernetes cluster. ## Install the Chart To install the services, run the following from the root of the chart directory: ```bash theme={null} helm install node-react . ``` > [!TIP] > > The `helm install` command would pick the values from `values.yaml` and spin up the cluster. Alternatively, you > can create another file called \`local-values > > .yaml`which contains the local images, and`values.yaml\` can have actual default values. To use another YAML file instead of the default `values.yaml` for local development, run: ```bash theme={null} helm install -f local-values.yaml node-react . ``` If the installation is successful, you would see the following in your terminal output: ```text theme={null} NAME: node-react LAST DEPLOYED: NAMESPACE: default STATUS: deployed REVISION: 1 TEST SUITE: None ``` This will bring up 3 pods for each service/deployment we created. Run the following command to see the list of pods running: ```bash theme={null} watch -n 2 kubectl get all ``` You should see the following in your terminal: ```text theme={null} NAME READY STATUS RESTARTS AGE pod/backend-587b6668c5-fdgkt 1/1 Running 0 2m8s pod/frontend-84c4bb6dd6-n79f8 1/1 Running 0 2m8s pod/gateway-5b4bb95966-w9g7k 1/1 Running 0 2m8s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/backend ClusterIP 10.101.127.13 3000/TCP 2m8s service/frontend ClusterIP 10.106.145.105 80/TCP 2m8s service/gateway NodePort 10.97.166.143 80:31517/TCP 2m8s service/kubernetes ClusterIP 10.96.0.1 443/TCP 43h NAME READY UP-TO-DATE AVAILABLE AGE deployment.apps/backend 1/1 1 1 2m8s deployment.apps/frontend 1/1 1 1 2m8s deployment.apps/gateway 1/1 1 1 2m8s NAME DESIRED CURRENT READY AGE replicaset.apps/backend-587b6668c5 1 1 1 2m8s replicaset.apps/frontend-84c4bb6dd6 1 1 1 2m8s replicaset.apps/gateway-5b4bb95966 1 1 1 2m8s ``` To get the URL of the gateway service, run: ```bash theme={null} minikube service gateway --url ``` It would print the URL. Now you can access the: * Frontend at `http://127.0.0.1:/` * Backend at `http://127.0.0.1:/api/` #### Alternatively, you could also use Minikube tunnel to view the app. Change the `gateway.service.type` in the gateway from `NodePort` to `LoadBalancer`: ```yaml theme={null} gateway: port: 4000 service: type: LoadBalancer ``` and run: ```bash theme={null} minikube tunnel ``` Now you can access the: * Frontend at `http://localhost:4000/` * Backend at `http://localhost:4000/api/` > [!WARNING] > > LoadBalancer should be used only for development purposes. While pushing Helm charts to production for use with > LocalOps, use `NodePort`. ## Uninstalling the Helm App To clean up the app, run the following: ```bash theme={null} helm uninstall node-react minikube stop # to stop the Minikube ``` ## Before Publishing to Helm Registry > [!NOTE] > > Remove the `imagePullPolicy: IfNotPresent` from the deployment scripts. This is needed only to test the local images. > > Replace the repository in your `values.yaml` with actual registry images or use the custom YAML via the `-f` flag in the > Helm CLI. ## Example app ```text theme={null} FullStack Source: https://github.com/localopsco/node-todo-example FrontEnd Source: https://github.com/localopsco/js-example-spa ``` `node-todo-example` is a full-stack application that uses `Node.js` for the backend, `PostgreSQL` for the database, and `React` for the frontend. The FrontEnd application is built seperarely, the node app uses the images published by `js-example-spa` from public ECR to complete a full stack application This project is dockerized and the images are published to Amazon Elastic Container Registry (ECR). A Helm chart is also prepared and published to ECR. ## Next Steps Now we have the chart ready. The next steps would be: * [Publishing your Helm charts](/bring-your-helm-charts/publish/ecr) * [Creating an app](https://help.localops.co/en/articles/9580323-apps) * [Creating a release](https://help.localops.co/en/articles/9582027-releases) * [Deploy 🚀](https://help.localops.co/en/articles/9582075-app-environments) [Docker]: https://docs.docker.com/ [Helm]: https://helm.sh/ [Minikube]: https://minikube.sigs.k8s.io/docs/ [Kubernetes]: https://kubernetes.io/ # Python + React Source: https://docs.localops.co/bring-your-helm-charts/tutorials/python-react In this tutorial, we will integrate a backend (Django) app with a frontend (React.js) app by preparing a Helm chart. ## Prerequisites * [Docker] to build standalone containers to serve your production app. * [Helm] package that contains all the resources you need to deploy an application to a [Kubernetes] cluster. * [Minikube] to set up Kubernetes clusters locally. > [!NOTE] > > This guide assumes that you have basic knowledge of the above-mentioned technologies and tools. If you are not > familiar with any of them, it is highly recommended to review their official documentation and tutorials to get up to > speed before proceeding with this guide. > > By this time, it is assumed that you have a backend with Django and a frontend application, both dockerized and > published to a registry. If not, check out these guides to get you started before proceeding further: * [Building and packaging a Python app using Django](/guides/languages/python) * [Building and packaging a React app](/guides/spa/react) * [Publishing Docker images to a registry](/bring-your-helm-charts/first-steps/have-docker#push-the-image-to-ecr) ## Setup Minikube [Minikube] is local Kubernetes, focusing on making it easy to learn and develop for Kubernetes. Refer to the [installation guide](https://minikube.sigs.k8s.io/docs/start) for installing Minikube on your machine. Since we are building and testing the images locally, you might have built the [react-app](/guides/spa/react) and [python-app](/guides/languages/python) already. In short, run these commands from the root of the respective project to build the images: ```bash theme={null} # Build the frontend (react-app) Docker image docker build -t react-app:latest . # Build the backend (python-app) Docker image docker build -t python-app:latest . ``` Once the images are built, we need to load them into Minikube: ```bash theme={null} # Load the images into Minikube minikube image load react-app:latest minikube image load python-app:latest ``` The above command takes the mentioned image that is available as an archive and makes it available in the cluster. ## Create Helm Chart For this guide, we'll create a simple chart called `python-react-chart`, and then we'll create some templates inside of the chart. ```bash theme={null} helm create python-react-chart ``` Once the chart is created, it will have some default templates. We don't need them for now. Let's copy them to another folder called `templates-bak`. You might need them later for reference or you can remove them. ```bash theme={null} mv python-react-chart/templates python-react-chart/templates-bak ``` > [!TIP] > > When you're writing production-grade charts, having basic versions of these charts can be really useful. So in your > day-to-day chart authoring, you probably won't want to remove them. Now, create a templates directory for us to write new templates. ```bash theme={null} cd python-react-chart mkdir templates ``` ### Create/Modify `values.yaml` Assume that you have built the images locally. You might have a `values.yaml` file in the root directory created by Helm with sample content. Let's clear the contents and update them with the following to specify the images and the tag to be used for deployments. ```yaml values.yaml theme={null} frontend: image: repository: react-app tag: latest env: PORT: 80 backend: image: repository: python-app tag: latest env: PORT: 3000 gateway: port: 80 service: type: NodePort image: # using the alpine version of Nginx to reduce bundle size repository: nginx tag: alpine ``` > [!NOTE] > > Here we are using the locally built images for testing. In a real app scenario, the repository will be replaced with > the actual registry URL depending on where it is published. For example, if your app is published in public AWS ECR, the input will be like: ```yaml theme={null} frontend: image: repository: public.aws.ecr//react-app tag: latest # or the explicit version tag: v1.0.0 ``` ### Create Deployments/Kubernetes Manifests Now let's create deployments for all three services: * **frontend** - a React app * **backend** - a Python app built with Django * **gateway** - an Nginx server to route traffic to the frontend and backend depending on the URL path #### Frontend Deployment Let's create a manifest that will create a deployment for the frontend application, specifying the Docker image and setting the `PORT` environment variable. It also creates a service to expose the frontend application. ```yaml templates/frontend.yaml theme={null} apiVersion: apps/v1 kind: Deployment metadata: name: frontend spec: replicas: 1 selector: matchLabels: app: frontend template: metadata: labels: app: frontend spec: containers: - name: frontend image: '{{ .Values.frontend.image.repository }}:{{ .Values.frontend.image.tag }}' # set the imagePullPolicy only while testing local images # skip this while using registry images imagePullPolicy: IfNotPresent ports: - containerPort: { { .Values.frontend.env.PORT } } env: - name: PORT value: '{{ .Values.frontend.env.PORT }}' --- apiVersion: v1 kind: Service metadata: name: frontend spec: selector: app: frontend ports: - protocol: TCP port: { { .Values.frontend.env.PORT } } targetPort: { { .Values.frontend.env.PORT } } ``` #### Backend Deployment Create another manifest that will create a deployment for the backend application, specifying the Docker image and setting the `PORT` environment variable. It also creates a service to expose the backend application. ```yaml templates/backend.yaml theme={null} apiVersion: apps/v1 kind: Deployment metadata: name: backend spec: replicas: 1 selector: matchLabels: app: backend template: metadata: labels: app: backend spec: containers: - name: backend image: '{{ .Values.backend.image.repository }}:{{ .Values.backend.image.tag }}' # set the imagePullPolicy only while testing local images # skip this while using registry images imagePullPolicy: IfNotPresent ports: - containerPort: { { .Values.backend.env.PORT } } env: - name: PORT value: '{{ .Values.backend.env.PORT }}' --- apiVersion: v1 kind: Service metadata: name: backend spec: selector: app: backend ports: - protocol: TCP port: { { .Values.backend.env.PORT } } targetPort: { { .Values.backend.env.PORT } } ``` #### Gateway Deployment We need one more manifest, which will create a deployment for the Nginx gateway. This gateway service will route traffic to the frontend and backend services based on the request path. It also creates a service to expose the gateway. ```yaml templates/gateway.yaml theme={null} apiVersion: apps/v1 kind: Deployment metadata: name: gateway spec: replicas: 1 selector: matchLabels: app: gateway template: metadata: labels: app: gateway spec: containers: - name: gateway image: '{{ .Values.gateway.image.repository }}:{{ .Values.gateway.image.tag }}' ports: - containerPort: { { .Values.gateway.port } } volumeMounts: - name: nginx-config mountPath: /etc/nginx/nginx.conf subPath: nginx.conf volumes: - name: nginx-config configMap: name: nginx-config --- apiVersion: v1 kind: Service metadata: name: gateway spec: type: { { .Values.gateway.service.type } } selector: app: gateway ports: - protocol: TCP port: { { .Values.gateway.port } } targetPort: { { .Values.gateway.port } } ``` #### Nginx ConfigMap This ConfigMap defines the Nginx configuration, specifying the routing rules to direct traffic to the appropriate service based on the request path. ```yaml templates/nginx-config.yaml theme={null} apiVersion: v1 kind: ConfigMap metadata: name: nginx-config data: nginx.conf: | events { } http { upstream frontend { server frontend:{{ .Values.frontend.env.PORT }}; } upstream backend { server backend:{{ .Values.backend.env.PORT }}; } server { listen {{ .Values.gateway.port }}; location / { proxy_pass http://frontend; } location /api/ { rewrite ^/api/(.*) /$1 break; proxy_pass http://backend; } } } ``` Hurray 🎉! Now we have the chart ready. Next is to install and run the app in the local Kubernetes cluster. ## Install the Chart To install the services, run the following from the root of the chart directory: ```bash theme={null} helm install python-react . ``` > [!TIP] > > The `helm install` command would pick the values from `values.yaml` and spin up the cluster. Alternatively, you > can create another file called \`local-values > > .yaml`which contains the local images, and`values.yaml\` can have actual default values. To use another YAML file instead of the default `values.yaml` for local development, run: ```bash theme={null} helm install -f local-values.yaml python-react . ``` If the installation is successful, you would see the following in your terminal output: ```text theme={null} NAME: python-react LAST DEPLOYED: NAMESPACE: default STATUS: deployed REVISION: 1 TEST SUITE: None ``` This will bring up 3 pods for each service/deployment we created. Run the following command to see the list of pods running: ```bash theme={null} watch -n 2 kubectl get all ``` You should see the following in your terminal: ```text theme={null} NAME READY STATUS RESTARTS AGE pod/backend-587b6668c5-fdgkt 1/1 Running 0 2m8s pod/frontend-84c4bb6dd6-n79f8 1/1 Running 0 2m8s pod/gateway-5b4bb95966-w9g7k 1/1 Running 0 2m8s NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE service/backend ClusterIP 10.101.127.13 3000/TCP 2m8s service/frontend ClusterIP 10.106.145.105 80/TCP 2m8s service/gateway NodePort 10.97.166.143 80:31517/TCP 2m8s service/kubernetes ClusterIP 10.96.0.1 443/TCP 43h NAME READY UP-TO-DATE AVAILABLE AGE deployment.apps/backend 1/1 1 1 2m8s deployment.apps/frontend 1/1 1 1 2m8s deployment.apps/gateway 1/1 1 1 2m8s NAME DESIRED CURRENT READY AGE replicaset.apps/backend-587b6668c5 1 1 1 2m8s replicaset.apps/frontend-84c4bb6dd6 1 1 1 2m8s replicaset.apps/gateway-5b4bb95966 1 1 1 2m8s ``` To get the URL of the gateway service, run: ```bash theme={null} minikube service gateway --url ``` It would print the URL. Now you can access the: * Frontend at `http://127.0.0.1:/` * Backend at `http://127.0.0.1:/api/` #### Alternatively, you could also use Minikube tunnel to view the app. Change the `gateway.service.type` in the gateway from `NodePort` to `LoadBalancer`: ```yaml theme={null} gateway: port: 4000 service: type: LoadBalancer ``` and run: ```bash theme={null} minikube tunnel ``` Now you can access the: * Frontend at `http://localhost:4000/` * Backend at `http://localhost:4000/api/` > [!WARNING] > > LoadBalancer should be used only for development purposes. While pushing Helm charts to production for use with > LocalOps, use `NodePort`. ## Uninstalling the Helm App To clean up the app, run the following: ```bash theme={null} helm uninstall python-react minikube stop # to stop the Minikube ``` ## Before Publishing to Helm Registry > [!NOTE] > > Remove the `imagePullPolicy: IfNotPresent` from the deployment scripts. This is needed only to test the local > images. > > Replace the repository in your `values.yaml` with actual registry images or use the custom YAML via the `-f` flag in the > Helm CLI. ## Next Steps Now we have the chart ready. The next steps would be: * [Publishing your Helm charts](/bring-your-helm-charts/publish/ecr) * [Creating an app](https://help.localops.co/en/articles/9580323-apps) * [Creating a release](https://help.localops.co/en/articles/9582027-releases) * [Deploy 🚀](https://help.localops.co/en/articles/9582075-app-environments) [Docker]: https://docs.docker.com/ [Helm]: https://helm.sh/ [Minikube]: https://minikube.sigs.k8s.io/docs/ [Kubernetes]: https://kubernetes.io/ # Install on Linux Source: https://docs.localops.co/cli/install-linux ## Install LocalOps CLI To quickly install or update the LocalOps CLI on your Linux distribution, run the following command in your terminal: ```bash theme={null} bash -c "$(curl -fsSL https://cli.localops.co/install.sh)" ``` This script downloads and installs the `ops` CLI to your system's PATH. > [!NOTE] > > You may be prompted to enter your password during the installation process. You can view the source code for the installation script on [GitHub](https://github.com/localopsco/lops-cli/blob/main/install.sh). ## Download Binaries If you prefer to download the binary directly, you can choose the appropriate version for your Linux: * [Linux arm64](https://github.com/localopsco/lops-cli/releases/latest/download/lops-linux-arm64.tar.gz) * [Linux x86\_64 / amd64](https://github.com/localopsco/lops-cli/releases/latest/download/lops-linux-amd64.tar.gz) ## Verify Installation After installation, verify that the `ops` CLI is installed correctly by running: ```bash theme={null} ops version ``` This command should display the CLI version, confirming that the installation was successful. 🚀 ## Uninstall CLI To uninstall the CLI installed via the install script, run the following command: ```bash theme={null} bash -c "$(curl -fsSL https://cli.localops.co/uninstall.sh)" ``` If you have manually downloaded the binary, just delete it. ## Source Code Our binaries and installation scripts are hosted in our public GitHub repository: [LocalOps CLI GitHub Repo](https://github.com/localopsco/lops-cli). # Install on macOS Source: https://docs.localops.co/cli/install-macos ## Install LocalOps CLI To quickly install or update the LocalOps CLI on your macOS distribution, run one of the following commands in your terminal: **Homebrew** ```bash theme={null} brew install localopsco/tap/ops ``` **Install script** ```bash theme={null} bash -c "$(curl -fsSL https://cli.localops.co/install.sh)" ``` This script downloads and installs the `ops` CLI to your system's PATH. > [!NOTE] > > You may be prompted to enter your password during the installation process. You can view the source code for the installation script on [GitHub](https://github.com/localopsco/lops-cli/blob/main/install.sh). ## Download Binaries If you prefer to download the binary directly, you can choose the appropriate version for your Mac: * [macOS (Apple Silicon)](https://github.com/localopsco/lops-cli/releases/latest/download/lops-darwin-arm64.tar.gz) * [macOS (Intel Chip)](https://github.com/localopsco/lops-cli/releases/latest/download/lops-darwin-amd64.tar.gz) ## Verify Installation After installation, verify that the `ops` CLI is installed correctly by running: ```bash theme={null} ops version ``` This command should display the CLI version, confirming that the installation was successful. 🚀 ## Uninstall CLI To uninstall the CLI installed via the install script, run the following command: ```bash theme={null} bash -c "$(curl -fsSL https://cli.localops.co/uninstall.sh)" ``` If you have manually downloaded the binary, just delete it. ## Source Code Our binaries and installation scripts are hosted in our public GitHub repository: [LocalOps CLI GitHub Repo](https://github.com/localopsco/lops-cli). # Install on Windows Source: https://docs.localops.co/cli/install-windows ## Install LocalOps CLI There are two ways to install LocalOps CLI on a Windows machine * [Downloading Binaries](#downloading-binaries) — recommended, runs natively on Windows * [Using WSL](#using-wsl) — fallback, if you would rather work inside a Linux environment ## Downloading Binaries Download the Windows binary and run it directly. Pick the build that matches your processor architecture: * [Windows arm64](https://github.com/localopsco/lops-cli/releases/latest/download/ops-windows-arm64.zip) — for ARM devices such as Surface Pro X or Copilot+ PCs * [Windows x86\_64 / amd64](https://github.com/localopsco/lops-cli/releases/latest/download/ops-windows-amd64.zip) — for most Intel and AMD machines Both links always point to the latest release. You can also browse all versions and download an older build from the [releases page](https://github.com/localopsco/lops-cli/releases). > [!NOTE] > > Not sure which one you need? Run `echo $env:PROCESSOR_ARCHITECTURE` in PowerShell. `AMD64` means you need the amd64 > build, `ARM64` means you need the arm64 build. ### Extract the binary Open PowerShell in the folder where the file was downloaded (usually `Downloads`) and extract the archive. Replace `amd64` with `arm64` in the commands below if you downloaded the ARM build. ```powershell theme={null} cd $HOME\Downloads Expand-Archive -Path .\ops-windows-amd64.zip -DestinationPath $HOME\localops -Force ``` This extracts `ops.exe` into `C:\Users\\localops`. > [!TIP] > > If you prefer a GUI, right-click the downloaded `.zip` file in File Explorer, choose **Extract All...**, and pick a > folder you can find easily. ### Run the binary You can now run the CLI using its full path: ```powershell theme={null} & $HOME\localops\ops.exe version ``` ### Add to PATH (recommended) To run `ops` from any directory without typing the full path, add the folder to your user `PATH`: ```powershell theme={null} [Environment]::SetEnvironmentVariable( 'Path', [Environment]::GetEnvironmentVariable('Path', 'User') + ';' + "$HOME\localops", 'User' ) ``` > [!NOTE] > > Close and reopen your terminal for the `PATH` change to take effect. ### Verify installation Verify that the CLI is installed correctly by running: ```powershell theme={null} ops version ``` This command should display the CLI version, confirming that the installation was successful 🚀 ### Update the CLI To update, download the latest zip and extract it over the same folder: ```powershell theme={null} cd $HOME\Downloads Expand-Archive -Path .\ops-windows-amd64.zip -DestinationPath $HOME\localops -Force ``` The `-Force` flag overwrites the existing `ops.exe`. ## Using WSL If you would rather work inside a Linux environment, or the native binary does not suit your setup, you can install the CLI through WSL instead. WSL is a feature developed by Microsoft that allows you to run a Linux distribution on your Windows machine. This feature is supported on Windows 10 and above. For older versions of Windows, you may have to [install it manually](https://learn.microsoft.com/en-us/windows/wsl/install-manual). ### Install WSL You can choose your choice of Linux distro, in this example, we will be using Ubuntu. Open PowerShell or Windows Command Prompt in administrator mode by right-clicking and selecting "Run as administrator", enter the following command ```bash theme={null} wsl --install -d ubuntu ``` > [!NOTE] > > You'll need to restart your machine after the installation Check out [Official WSL docs](https://learn.microsoft.com/en-us/windows/wsl/install) for more info. After the reboot, run the command from your PowerShell ```bash theme={null} wsl ``` Once you have installed WSL, you will need to create a user account and password for your newly installed Linux distribution. > [!NOTE] > > This user is not the same as your Windows user. ### Install CLI Once you have everything up and running, you can install LocalOps CLI by following the instructions from the [Install Linux](/cli/install-linux) page. Since we are running a linux distribution on a windows machine, steps are the same. ## Source Code Our binaries and installation scripts are hosted in our public GitHub repository: [LocalOps CLI GitHub Repo](https://github.com/localopsco/lops-cli). # Usage Source: https://docs.localops.co/cli/usage LocalOps CLI `ops` can be used to read logs from your services, get shell access to them and to their databases, forward their ports to your machine, and reach the underlying Kubernetes cluster of an environment. ``` LocalOps CLI Usage: ops [command] Available Commands: completion Generate the autocompletion script for the specified shell connect Open a shell in a service's pod get-token Print a Kubernetes ExecCredential for an app environment cluster help Help about any command login Login to LocalOps Account logout Logout of LocalOps Account logs Show logs from a service running in an environment project Show and switch the active project proxy Forward a service's port to localhost update-kubeconfig Update current context to app environment kubernetes cluster version LocalOps CLI Version Flags: -h, --help help for ops Use "ops [command] --help" for more information about a command. ``` ### How it works For the things you reach for most often - reading logs, opening a shell, forwarding a port, connecting to a database - `ops logs`, `ops connect` and `ops proxy` talk to your environment directly. You need neither `kubectl` nor the pod and namespace names: 1. Login to your LocalOps account with `ops login` 2. Run `ops logs`, `ops connect` or `ops proxy` against an environment and service by name To inspect anything else in the cluster - deployments, jobs, secrets, events - point `kubectl` at the environment instead: 1. Login to your LocalOps account with `ops login` 2. Set the Kubernetes context of `kubectl` to point at the environment's cluster with `ops update-kubeconfig` 3. Then use `kubectl` to inspect the cluster ### Who can run which command What you can do with the CLI depends on your [role](/team/understanding-roles) in the environment you point it at, your project role, or your environment role in a [protected environment](/environment/protected-environments). | Command | Read-only | Maintainer | Member | Owner / Admin (unrestricted) | | - | - | - | - | - | | `ops login`, `ops logout`, `ops project` | ✅ | ✅ | ✅ | ✅ | | `ops logs` | ❌ | ✅ | ✅ | ✅ | | `ops connect` (including `--dep`) | ❌ | ❌ | ✅ | ✅ | | `ops proxy` (including `--dep`) | ❌ | ❌ | ✅ | ✅ | | `ops update-kubeconfig`, `kubectl`, k9s | ❌ | ❌ | ✅ | ✅ | An owner or admin who is [restricted](/team/owner-admin-restrictions) in a project or environment gets the column of the role they are restricted to. Commands your role doesn't allow stop with a message such as: ``` Error: your role in this environment (maintainer) doesn't allow `ops connect`, it needs member or higher ``` ### Login to LocalOps ```sh theme={null} ops login ``` ## Basic usage Reading logs, opening a shell and forwarding a port - each of these takes an environment and a service by name. ### Stream logs from a service `ops logs` streams logs from a service straight to your terminal: ```sh theme={null} ops logs --env staging --svc api ``` `--env` and `--svc` take the environment and service **names** shown in your dashboard, or their ids. `--svc` is required; `--env` falls back to the `ENV` environment variable when you leave it out. The stream stays open and prints new lines as they arrive - press `Ctrl-C` to stop. Pass `--follow=false` for a snapshot that prints and exits. When a service runs more than one pod, all of them are read at once and every line is prefixed with the pod it came from, so you can tell replicas apart: ``` [api-7d9f8b6c4-2xk9p] GET /health 200 [api-7d9f8b6c4-mn4vt] GET /orders 201 ``` | Flag | Default | Description | | - | - | - | | `-e, --env` | `$ENV` | Environment name or id | | `-s, --svc` | - | Service name or id (required) | | `-f, --follow` | `true` | Keep the stream open and print new lines as they arrive | | `-n, --tail` | `100` | Number of recent lines to show. `0` shows everything the cluster still holds | | `-S, --since` | - | Only show logs newer than this, e.g. `15m` or `2h` | | `-T, --timestamps` | `false` | Prefix each line with its timestamp | | `-i, --interactive` | `false` | Pick a single pod to read, instead of reading all of them | | `-p, --project` | - | Project id to use, instead of the session's active project | ```sh theme={null} ops logs --env staging --svc api --tail 500 --timestamps ops logs --env staging --svc api --since 15m ops logs --env staging --svc api --follow=false ``` > [!NOTE] > > `--tail` and `--since` apply to each pod, not to the service as a whole - > `--tail 100` against a service with three pods can print up to 300 lines. > Lines are printed as they arrive rather than merged into one chronological > order, so add `--timestamps` when ordering across replicas matters. ### Shell into a service `ops connect` opens a shell inside a pod of your service, without looking up pod or namespace names: ```sh theme={null} ops connect --env staging --svc api ``` That gives you `/bin/sh` on the first ready pod. To use a different shell, or to run a single command and exit, put it after `--`: ```sh theme={null} ops connect --env staging --svc api -- /bin/bash ops connect --env staging --svc api -- printenv DATABASE_URL ``` | Flag | Default | Description | | - | - | - | | `-e, --env` | `$ENV` | Environment name or id | | `-s, --svc` | - | Service name or id (required) | | `-i, --interactive` | `false` | Pick which pod to open, instead of taking the first ready one | | `-p, --project` | - | Project id to use, instead of the session's active project | Both commands take the default pod selection silently so they stay usable in scripts. Add `-i` when you want to choose instead. On a service with several pods it shows a list of them, and the first entry keeps the default behaviour: ```sh theme={null} ops logs -e staging -s api -i ops connect -e staging -s api -i ``` > [!WARNING] > > `ops connect` puts you on a live container serving traffic. Anything you > change inside it is lost the next time the pod restarts or is replaced by a > [deployment](/environment/services/deploy) - use it to inspect and debug, and > make lasting changes through your repo instead. ### Forward a service port to localhost `ops proxy` opens a tunnel from your machine to a service running in an environment, so you can reach an internal service as though it were running locally: ```sh theme={null} ops proxy --env staging --svc api ``` It runs in the foreground and closes the tunnel when you stop it with `Ctrl-C`. By default it binds the same port locally that the service listens on, taken from the service's configuration. | Flag | Default | Description | | - | - | - | | `-e, --env` | `$ENV` | Environment name or id | | `-s, --svc` | - | Service name or id (required) | | `-L, --local-port` | the remote port | Local port to bind | | `-R, --remote-port` | the service's port | Port on the service to forward to | | `-i, --interactive` | `false` | Pick which pod to forward from | | `-p, --project` | - | Project id to use, instead of the session's active project | ```sh theme={null} ops proxy --env staging --svc api --local-port 9000 ops proxy --env staging --svc api --remote-port 9090 --local-port 9000 ``` > [!NOTE] > > The tunnel attaches to a single pod, so it does not load balance across > replicas. That is usually what you want when debugging, but it means > restarting that pod ends the tunnel. ## Connect to your databases or cache Resources provisioned through `ops.json` - [RDS instances](/environment/services/aws/rds), [ElastiCache clusters](/environment/services/aws/elasti-cache) and [MSK clusters](/environment/services/aws/msk) - live in the private subnets of your environment's VPC and only accept connections from inside it. There is no public endpoint to point a client at from your laptop, by design. So you connect from a throwaway pod inside the cluster instead. `ops connect --dep` and `ops proxy --dep` do that for you: they start a short-lived pod in your environment, connect it to the database, cache or Kafka cluster, and clean it up when you exit. They work with: | Dependency | Engine | Shell client | Client image | | - | - | - | - | | RDS | Postgres | `psql` | `postgres:17-alpine` | | RDS | MySQL | `mysql` | `mysql:8.4` | | RDS | SQL Server | `usql` | `usql/usql:0.21.6` | | ElastiCache | Redis, Valkey | `redis-cli` | `redis:7-alpine` | | MSK | Kafka, provisioned or serverless | Kafka's own scripts (`kafka-topics.sh`, ...) | `apache/kafka:3.9.1` | MSK clusters work with `ops connect --dep` only, not `ops proxy --dep`: Kafka clients reach every broker by its private hostname, so a tunnel to one address on your machine cannot serve them. > [!NOTE] > > These commands only reach resources you provisioned through `ops.json` - for example an [RDS > instance](/environment/services/aws/rds) or an [ElastiCache cluster](/environment/services/aws/elasti-cache). LocalOps > creates those inside your environment's VPC and injects their connection details into your service, which is what > `--dep` reads. A database you host or manage yourself is not reachable this way. ### First, export the connection details `--dep` finds a dependency by what its `exports` in `ops.json` hand to your service, so it needs one of these. **For a database, export `$dsn`.** It is a complete, ready-to-use connection URL that LocalOps assembles for you - host, port, username, password and database name already filled in and correctly escaped: ```json ops.json theme={null} { "dependencies": { "rds": { "instances": [ { "id": "app-db", "prefix": "appdb", "engine": "postgres", "version": "17.5", "exports": { "DATABASE_URL": "$dsn" } } ] } } } ``` A MySQL instance is the same, with `"engine": "mysql"`. A [SQL Server instance](/environment/services/aws/rds#sql-server) is the same with one of the SQL Server engines - `sqlserver-ex`, `sqlserver-web`, `sqlserver-se` or `sqlserver-ee`. RDS creates no database on a SQL Server instance, so its `$dsn` has no database name and you land in the server's default database. **For a Redis cache, export `$endpoint`** - or `$address` together with `$port`. ElastiCache needs no password, so the address is all `--dep` needs: ```json ops.json theme={null} { "dependencies": { "elasticache": { "clusters": [ { "id": "sessions", "prefix": "sessions", "engine": "redis", "version": "7.0", "instance_type": "cache.t4g.small", "exports": { "REDIS_ENDPOINT": "$endpoint" } } ] } } } ``` **For an MSK cluster, export `$bootstrapBrokers`.** A provisioned cluster also needs its `$username` and `$password` exported, since it authenticates with them. A serverless cluster authenticates with your service's IAM role and needs nothing else. Export `$saslMechanism` too, so the client knows which of the two to use: ```json ops.json theme={null} { "dependencies": { "msk": { "clusters": [ { "id": "events", "type": "provisioned", "version": "3.9.x", "exports": { "KAFKA_BROKERS": "$bootstrapBrokers", "KAFKA_USERNAME": "$username", "KAFKA_PASSWORD": "$password", "KAFKA_SASL_MECHANISM": "$saslMechanism" } } ] } } } ``` Deploy once, and every container of that service has those variables in its environment. > [!WARNING] > > `$dsn` embeds the database password, so handle the value exactly as you would a password. Don't paste it into tickets, > Slack messages or shared docs, don't commit it, and don't save it into a GUI client's connection profile - read it > from a pod each time you need it. When `managed_password` is `true`, RDS rotates the password on its own schedule, so > a copied URL is both a leaked secret and a value with an expiry date. ### Open a database shell ```sh theme={null} ops connect --env staging --svc api --dep ``` That starts a client pod in your environment and drops you at the engine's own prompt - `psql`, `mysql`, `usql` or `redis-cli` from the table above, or a shell with the Kafka CLI for MSK. Exit the shell and the pod is deleted. Bare `--dep` picks the dependency for you when the service has exactly one database, cache or MSK cluster. Name it when there are several - either by its `ops.json` id or by the variable it exports: ```sh theme={null} ops connect --env staging --svc api --dep app-db ops connect --env staging --svc api --dep sessions ops connect --env staging --svc api --dep events ``` > [!NOTE] > > SQL Server opens in [usql](https://github.com/xo/usql) rather than `sqlcmd`, because Microsoft publishes no `sqlcmd` > image that runs on ARM nodes. usql's prompt works like `psql`: end each statement with `;` instead of `GO`, and type > `\q` to quit. > [!NOTE] > > Memcached clusters are not supported. `--db-image` overrides the client image, for example to match your MySQL > server's major version - an older client against a newer server can fail on newer authentication methods. > [!TIP] > > A database password is never read by the CLI or printed to your terminal. The client pod is given the same Kubernetes > Secret reference your service has, so the password is injected by the cluster. It stays out of your shell history and > out of your scrollback. ### Open a Kafka shell ```sh theme={null} ops connect --env staging --svc api --dep events ``` For an MSK cluster, the client pod runs Apache Kafka's own command-line scripts. You land in a shell in `/opt/kafka/bin`, already set up to reach the cluster: ``` Connected to events (SCRAM-SHA-512). The Kafka CLI is in /opt/kafka/bin, set up with: $BOOTSTRAP_SERVERS b-1.events.xxxxxx.c2.kafka.ap-south-1.amazonaws.com:9096,... $CLIENT_CONFIG /tmp/ops-kafka/client.properties kafka:events:/opt/kafka/bin> ``` `$BOOTSTRAP_SERVERS` holds the cluster's brokers and `$CLIENT_CONFIG` a client configuration with its authentication, so every script works with the same two flags: ```sh theme={null} # list and create topics ./kafka-topics.sh --bootstrap-server $BOOTSTRAP_SERVERS --command-config $CLIENT_CONFIG --list ./kafka-topics.sh --bootstrap-server $BOOTSTRAP_SERVERS --command-config $CLIENT_CONFIG --create --topic orders --partitions 3 # publish: one message per line, Ctrl-D to stop ./kafka-console-producer.sh --bootstrap-server $BOOTSTRAP_SERVERS --producer.config $CLIENT_CONFIG --topic orders # read everything on the topic, Ctrl-C to stop ./kafka-console-consumer.sh --bootstrap-server $BOOTSTRAP_SERVERS --consumer.config $CLIENT_CONFIG --topic orders --from-beginning # consumer groups and their lag ./kafka-consumer-groups.sh --bootstrap-server $BOOTSTRAP_SERVERS --command-config $CLIENT_CONFIG --list ./kafka-consumer-groups.sh --bootstrap-server $BOOTSTRAP_SERVERS --command-config $CLIENT_CONFIG --describe --group my-service ``` Exit the shell and the pod is deleted. Serverless clusters create no topics on their own, so create one before you produce to it. > [!NOTE] > > A serverless cluster has no password: the client pod runs with your service's IAM role, the same role your service > uses to reach the cluster. It also needs AWS's IAM library for Kafka, which the pod downloads from Maven Central (or > GitHub, as a fallback) when the shell opens and checks against a pinned checksum. The first connect therefore needs > outbound internet access from your environment. If that isn't available, pass `--db-image` with an image based on > `apache/kafka:3.9.1` that already has `aws-msk-iam-auth-2.3.9-all.jar` in `/opt/kafka/libs`. > [!TIP] > > Each Kafka script starts a Java process, so a command takes a second or two to begin. The client pod is sized for > that: it reserves 100m CPU and 128 MiB of memory, and can use up to 1 CPU and 512 MiB, enough for a consumer and a > producer running side by side. ### Use a local GUI client (TablePlus, DataGrip, DBeaver, RedisInsight) ```sh theme={null} ops proxy --env staging --svc api --dep app-db ``` That relays the private endpoint to your machine and prints the connection details to use for that engine: ``` psql -h localhost -p 5432 -U appuser -d appdb -W password: ``` ``` mysql -h 127.0.0.1 -P 3306 -u appuser -p appdb password: ``` ``` sqlcmd -S 127.0.0.1,1433 -U appuser -C password: ``` ``` redis-cli -h 127.0.0.1 -p 6379 ``` Point your GUI client at that host and port with those credentials, and leave the command running while you work. `Ctrl-C` closes the tunnel and removes the relay pod. Pass `--local-port` if the port is already taken locally - by a database you run on your own machine, for example: ```sh theme={null} ops proxy --env staging --svc api --dep app-db --local-port 15432 ``` > [!NOTE] > > MySQL's details use `127.0.0.1` rather than `localhost` on purpose: the `mysql` client treats `localhost` as its local > socket and never reaches the tunnel. > [!WARNING] > > Don't verify the database certificate's hostname through the tunnel. The certificate is issued for the database's real > hostname, not your machine, so that check fails. For Postgres use SSL mode `require` rather than `verify-full` - > `PGSSLMODE=require` for `psql`, which has no `sslmode` flag. For MySQL use `--ssl-mode=REQUIRED` rather than > `VERIFY_IDENTITY`. For SQL Server, trust the server certificate - `-C` in the `sqlcmd` command above, or **Trust > server certificate** in a GUI client. > [!WARNING] > > Every recipe on this page connects you to a real database. On production environments, prefer read-only queries and > keep in mind that anything you run has immediate effect - there is no staging step between your prompt and your > customers' data. ## Advanced workflows The commands above cover the day-to-day work without leaving the CLI. Reach for `kubectl` and [k9s](https://k9scli.io/) when you need to inspect anything else in the cluster - deployments, jobs, secrets, events - or to reach a pod that is not one of your own services. ### Set kubernetes context > [!NOTE] > > Needs the Member role or higher in the environment. See [who can run which command](#who-can-run-which-command). Use this command to point your local Kubernetes context at the environment's cluster. ```sh theme={null} ops update-kubeconfig -e env-id ``` The `env-id` is in the address of the environment's page in the LocalOps console. The **CLI** button on that page shows this command with the ID filled in. ### Use Kubectl After `update-kubeconfig` command succeeds, you can use any kubectl command to inspect pods, deployments, jobs and everything else running in your LocalOps environment. All your services are deployed in the `app-services` namespace. To see only your service pods: ```sh theme={null} kubectl get pods -n app-services ``` To see all cluster resources across all namespaces: ```sh theme={null} kubectl get all --all-namespaces ``` ### Monitor pods faster than kubectl with k9s [k9s](https://k9scli.io/) is a terminal-based UI that makes it easy to monitor and manage Kubernetes resources. After setting up your kubeconfig with `ops update-kubeconfig`, simply launch k9s: ```sh theme={null} k9s ``` k9s will automatically use the current Kubernetes context set by `ops update-kubeconfig`. To launch k9s directly in the `app-services` namespace where your services run: ```sh theme={null} k9s -n app-services ``` From the k9s interface you can: * View all pods and their status in real time * Watch logs by selecting a pod and pressing `l` * Filter resources by namespace using `/` to search * Delete, describe, or edit resources interactively > [!TIP] > > Install k9s via Homebrew with `brew install derailed/k9s/k9s` on macOS, or see > the [k9s installation guide](https://k9scli.io/topics/install/) for other > platforms. ### Shell into a pod [`ops connect`](#shell-into-a-service) is the shortest way to get a shell of one of your own services. Reach for `kubectl` when you need a shell on a pod that is not a LocalOps service - a database pod, or something you installed into the cluster yourself. To get a shell inside a running pod, first identify the pod name in the `app-services` namespace: ```sh theme={null} kubectl get pods -n app-services ``` Then exec into the pod: ```sh theme={null} kubectl exec -it -n app-services -- /bin/sh ``` > [!NOTE] > > Some containers may use `/bin/bash` instead of `/bin/sh`. If `/bin/sh` fails, > try `/bin/bash`. #### Shell into a pod using k9s [k9s](#monitor-pods-faster-than-kubectl-with-k9s) gets you the same shell in fewer keystrokes, and it saves you from having to know the pod name up front. Launch it against your services with `k9s -n app-services`, press `/` and type part of your service name to filter the list, move to the pod you want with the arrow keys, and press `s`. k9s opens an interactive shell inside that pod - the equivalent of the `kubectl exec` command above. If the pod runs more than one container (say your service plus a sidecar), press `Enter` on the pod first to list its containers, highlight the one you want, and press `s` there instead. When you are done, type `exit` or press `Ctrl-d` to close the shell and drop back into the k9s pod list, and `Esc` to back out of any k9s view. Unlike a hand-written `kubectl exec`, k9s tries a few common shells rather than a single hard-coded path, so the `/bin/sh` versus `/bin/bash` guesswork above usually doesn't come up. > [!WARNING] > > A shell opened this way is a shell on a live container serving traffic. > Anything you change inside it is lost the next time the pod restarts or is > replaced by a [deployment](/environment/services/deploy) - use it to inspect > and debug, and make lasting changes through your repo instead. ### Connect to a database with kubectl These recipes do the same work as [`ops connect --dep` and `ops proxy --dep`](#connect-to-your-databases-or-cache) by hand. Reach for them when you need something `--dep` does not cover yet - a database that exports discrete fields rather than `$dsn`, or a client `--dep` does not run, like `mysqlsh`. **Use `DATABASE_URL` instead of typing out ``, `` and `` yourself.** Hand-assembling the URL means looking up four separate values, escaping any special characters in the password correctly, and leaving credentials in your shell history - and it breaks silently the moment RDS rotates the password. Reading `$dsn` off a pod avoids all of that. List your pods, then read the variable off any pod belonging to that service: ```sh theme={null} kubectl get pods -n app-services ``` ```sh theme={null} kubectl exec -n app-services -- printenv DATABASE_URL ``` Start a one-shot client pod in the same namespace, passing the DSN straight from the running pod into the new one. The URL never lands in your shell history, and the client pod is deleted the moment you exit: ```sh theme={null} kubectl run db-client -n app-services -it --rm --restart=Never --image=postgres:17-alpine \ --env="PGURL=$(kubectl exec -n app-services -- printenv DATABASE_URL)" \ -- sh -c 'psql "$PGURL"' ``` MySQL is the same command with a different image and client. Use `mysqlsh`, which ships in the official `mysql:8` image and accepts the connection URL as-is - `--sql` starts it in SQL mode so it behaves like the classic `mysql` prompt: ```sh theme={null} kubectl run db-client -n app-services -it --rm --restart=Never --image=mysql:8 \ --env="DBURL=$(kubectl exec -n app-services -- printenv DATABASE_URL)" \ -- sh -c 'mysqlsh --sql "$DBURL"' ``` Reach for `mysqlsh` rather than the classic `mysql` client here, which takes discrete `-h` / `-u` / `-p` flags and no URL. Pick a client image whose major version matches your server too - an older client against a newer server can fail on newer authentication methods. If you haven't exported `$dsn` yet, you can still connect by spelling the credentials out and reading each value from `kubectl exec -n app-services -- printenv | grep -i db`, but adding `$dsn` to `exports` is a one-line change that makes every command above shorter and safer. Or relay the endpoint by hand, with a TCP forwarder pod and a port-forward to it: ```sh theme={null} kubectl run rds-proxy -n app-services --image=alpine/socat --port=5432 -- \ tcp-listen:5432,fork,reuseaddr tcp-connect::5432 ``` ```sh theme={null} kubectl port-forward -n app-services pod/rds-proxy 5432:5432 ``` Leave that running and point your GUI client at `localhost:5432`. Take the username, password and database name from the `DATABASE_URL` you read above rather than looking them up separately - most clients let you paste the whole URL and fill the fields in for you. Use SSL mode `require` rather than `verify-full`, since the certificate is issued for the database's real hostname, not `localhost`. Delete the forwarder when you're done: ```sh theme={null} kubectl delete pod rds-proxy -n app-services ``` Ephemeral [preview databases](/environment/services/ops-json#isolated-databases) run as pods in the cluster rather than as RDS instances, so they need no forwarder at all - `kubectl port-forward -n app-services pod/ 5432:5432` reaches them directly. # Compatibility Source: https://docs.localops.co/compatibility LocalOps supports: * **Amazon Web Services** - all AWS regions where EKS is supported. AWS has 39+ global regions. Learn more in [AWS site](https://aws.amazon.com/about-aws/global-infrastructure/). Opt-in regions such as Africa (Cape Town), `af-south-1`, are supported too - enable the region in your AWS account first. * **Google Cloud Platform** - all GCP regions where GKE is available. GCP has 43+ global regions. Learn more in [Google Cloud site](https://cloud.google.com/about/locations). Coming soon: * Microsoft Azure See what's planned next on our [public roadmap](https://github.com/orgs/localopsco/projects/9). Need support for another cloud provider or region? [Contact support](/support) and let us know. # Create environment Source: https://docs.localops.co/environment/create > [!NOTE] > > Needs the Member role in the project. See [Understanding roles](/team/understanding-roles#permissions-in-detail). To create a new environment: 1. Sign in to LocalOps. 2. Click on **Environments** from the navigation pane on the left side. 3. Click on **Create environment** button to create a new environment. 4. Pick Name, Connection, and Region. 5. Click on **Next: Review instance**. 6. Review the environment details, and if everything is correct, click the **"Looks good. Create environment."** button to start creating the environment. It may take anywhere between 18 - 20 minutes to complete environment creation process. You can see its progress either in Environments section or Ops section. # Delete environment Source: https://docs.localops.co/environment/delete Deleting environment does all the following: 1. Stops all services 2. Deletes all secrets you configured for services 3. Deletes all custom domains 4. Deletes monitoring stack 5. Deletes Kubernetes cluster 6. Deletes all cloud infrastructure - network, compute servers and volumes > [!WARNING] > > This is an irreversible action. > [!NOTE] > > Needs the Member role in the project, or in the environment if it's > [protected](/environment/protected-environments). See > [Understanding roles](/team/understanding-roles#permissions-in-detail). To proceed with deletion, you can follow these steps: 1. Click on **Environments** from the navigation pane on the left side to see the list of your environments. 2. Open the environment you want to delete and choose **Delete environment**. 3. Confirm by typing `delete `, then click **Continue** to start deleting the environment. Environment deletion may take anywhere between 10-15 minutes to complete. # Eject out of LocalOps Source: https://docs.localops.co/environment/eject There is no lock-in when you use LocalOps. You can stop using LocalOps anytime. All infrastructure resources are provisioned in the cloud accounts you connect. If you decide to stop using LocalOps, here are the steps and considerations to manage your environments and service deployments independently. ## Considerations * **Infrastructure Continuity**: Cloud resources including VPC, Subnets and Kubernetes cluster will continue to run on the same cloud account, even after ejecting from the platform. * **Deployments**: To trigger deployments on services, developers can use `kubectl` to make manual deployments. Github Actions can also be configured to connect to the Kubernetes cluster and do the same on git-push. Or ArgoCD can be setup on the respective cluster, to automate this further. * **Using IaC for Infrastructure**: If you choose to continue managing the infrastructure using Infrastructure as Code (IaC) independently, you can import the existing resources created by LocalOps into your IaC tool's state. This allows you to maintain and update infrastructure resources using the respective IaC tool. # Extend using Terraform/Pulumi Source: https://docs.localops.co/environment/extend-with-iac You may want to create additional cloud resources (Queues, Databases, Topics or anything) within a cloud account for any environment - dev, stage, prod, beyond what LocalOps has provisioned for the same environment. This guide explains how to extend environments using your Terraform/Pulumi scripts. At a high level, every environment comes with the following components that are provisioned and managed by LocalOps: * 1 VPC * 3 private subnets * 3 public subnets * a managed Kubernetes cluster (EKS in AWS) All your code is deployed and run as service(s) in the managed kubernetes cluster. You can provision additional cloud resources within the same VPC & subnets and they can be accessed from within your service(s) privately. To do this, we expose IDs of the above entities within LocalOps environment dashboard. ### Manual You can create cloud resources manually within the cloud console and use VPC/Subnet IDs in relevant places. ### Automate Add the VPC/Subnet IDs as variables in your Pulumi/Terraform scripts and automate those cloud resources. Say you want to create a RDS database for your environment. Here is how you will do it in Terraform, OpenTofu or Pulumi. ### Using Terraform or OpenTofu Here is how you can create an RDS database within the same private subnets and VPCs of the environment using Terraform or OpenTofu. ```hcl theme={null} variable "vpc_id" { description = "The ID of the VPC where RDS will be deployed" type = string } variable "subnet_ids" { description = "List of private subnet IDs for RDS" type = list(string) } resource "aws_db_subnet_group" "rds" { name = "custom-rds-subnet-group" subnet_ids = var.subnet_ids tags = { Name = "custom-rds-subnet-group" } } resource "aws_security_group" "rds_sg" { name = "rds-sg" description = "Security group for RDS" vpc_id = var.vpc_id ingress { from_port = 5432 to_port = 5432 protocol = "tcp" cidr_blocks = ["10.0.0.0/16"] } egress { from_port = 0 to_port = 0 protocol = "-1" cidr_blocks = ["0.0.0.0/0"] } tags = var.tags } resource "aws_db_instance" "main" { identifier = "example-db" engine = "postgres" instance_class = "db.t3.micro" allocated_storage = 20 username = "admin" password = "password123" db_subnet_group_name = aws_db_subnet_group.rds.name vpc_security_group_ids = var.vpc_security_group_ids skip_final_snapshot = true tags = { Name = "example-db" } } ``` ### Using Pulumi Here is a short example in Typescript, for provisioning a RDS database using Pulumi. Note that we can pass in VPC ID and subnet IDs as environment variable. ```ts theme={null} import * as aws from '@pulumi/aws'; const subnetIds = ['subnet-abc123', 'subnet-def456']; // pass from config const subnetGroup = new aws.rds.SubnetGroup('exampleSubnetGroup', { subnetIds: subnetIds, }); // Create Security Group for RDS const rdsSg = new aws.ec2.SecurityGroup('rds-sg', { vpcId, description: 'Allow Postgres from within VPC', ingress: [ { protocol: 'tcp', fromPort: 5432, toPort: 5432, cidrBlocks: ['10.0.0.0/16'], }, ], egress: [ { protocol: '-1', fromPort: 0, toPort: 0, cidrBlocks: ['0.0.0.0/0'], }, ], }); const db = new aws.rds.Instance('exampleDb', { engine: 'postgres', instanceClass: 'db.t3.micro', allocatedStorage: 20, username: 'admin', password: 'password123', dbSubnetGroupName: subnetGroup.name, vpcSecurityGroupIds: [rdsSg.id], skipFinalSnapshot: true, }); ``` > [!NOTE] > > We use `10.0.0.0/16` as CIDR range for any VPC we create. You can use the same as source IP or destination IP range > when defining security groups. ### Use same tags LocalOps creates all resources with two standard tags for any given environment. So that you can take inventory of all resources in the cloud, analyse cost per environment in Cost analysis console in the cloud account and more. These tags are exposed within environment Dashboard page. When you extend environments with custom cloud resources, you can attach the same tags so that you can see both the resources managed by LocalOps and those you created outside LocalOps for the same environment. ```hcl theme={null} variable "vpc_id" { type = string description = "VPC ID where the RDS will be deployed" } variable "subnet_ids" { type = list(string) description = "Subnet IDs for the DB subnet group" } variable "tags" { type = map(string) description = "Tags to apply to all resources" } resource "aws_db_subnet_group" "rds" { name = "custom-rds-subnet-group" subnet_ids = var.subnet_ids tags = var.tags } resource "aws_db_instance" "main" { identifier = "example-db" engine = "postgres" instance_class = "db.t3.micro" allocated_storage = 20 username = "admin" password = "password123" db_subnet_group_name = aws_db_subnet_group.rds.name vpc_security_group_ids = var.vpc_security_group_ids skip_final_snapshot = true tags = var.tags # passing same tags } ``` ### Resource lifecycle When you extend LocalOps environments with additional cloud resources either manually or by using Terraform-like IaC tools, you have to manage their configuration yourself for their lifetime. They won't be imported or managed by LocalOps. If you want to delete environments, you will have to first delete your terraform/opentofu/pulumi stack before deleting environment within LocalOps console. This is to ensure that all your additional cloud resources are deleted in full before VPC and other resources are deleted. # View your environment's resources Source: https://docs.localops.co/environment/infra-resources/aws Use LocalOps resource tags to find, inventory and analyze the cost of your environment's AWS resources We tag all the resources created by LocalOps with specific keys and values that you can use to locate your resources from your AWS console. These tags are useful for: * **Inventory** - list every AWS resource that belongs to an environment, so you always know what LocalOps provisioned in your account. * **Cost analysis** - break down your AWS bill by environment and see exactly how much each environment costs to run. ## View all resources in an environment 1. Find the tag keys and values added by LocalOps in your environment's **Overview** tab (**Environment > Overview**) 2. Open the [AWS Resource Explorer](https://resource-explorer.console.aws.amazon.com/resource-explorer/home#/search) from your AWS console 3. Search using the tag key and tag value to view all the resources associated with your application environment. Be sure to replace them with the ones from your environment's **Overview** tab. Tag key: ```text theme={null} tag.key:acmecorp.loc.env-id ``` Tag value: ```text theme={null} tag.value:627e8bb2-2667-46aa-943b-b93d5924fced ``` 4. You can further organize and manage these resources by creating [AWS Resource Groups](https://console.aws.amazon.com/resource-groups/home) using these tags. ## Analyze costs by environment 1. Open the [Cost allocation tags](https://console.aws.amazon.com/billing/home#/tags) page in the AWS Billing console 2. Find the LocalOps tag key (for example, `acmecorp.loc.env-id`) under **User-defined cost allocation tags** and activate it 3. Open [AWS Cost Explorer](https://console.aws.amazon.com/cost-management/home#/cost-explorer) and group or filter costs by that tag key to see the spend for each environment > [!NOTE] > > AWS can take up to 24 hours for a newly activated cost allocation tag to appear in Cost Explorer, and costs are only > tracked from the time the tag is activated. # What's inside? Source: https://docs.localops.co/environment/inside Each Application environment comprises **Classic VPC setup** * Dedicated Virtual private cloud (VPC) * Private subnets * Public subnets * NAT gateway * Internet gateway **Managed kubernetes cluster** * Cloud managed Kubernetes cluster (E.g., EKS in AWS) * Compute servers and their default volumes (E.g., EC2 in AWS) * Kubernetes components * Prometheus * Loki * Grafana * ELB (Elastic load balancer) for receiving all in-bound HTTP traffic * 👉 Your App Let us go over each of them in detail. ### Dedicated Virtual private cloud (VPC) In any connected cloud account, a dedicated network is provisioned to host everything for a given environment. In AWS, LocalOps provisions a VPC (Virtual private cloud). ### Private subnets Within the dedicated network / VPC, LocalOps creates private subnets to host data in servers having no public IP. ### Public subnets Similar to private subnets, LocalOps creates public subnets to host servers having public IP. For example, Internet gateway. ### NAT gateway In AWS, NAT Gateway and a persistent IP (elastic IP) is provisioned inside public subnet in each app environemnt for private subnet servers to connect to the internet. To the internet, all requests originating from private subnet servers will pass via NAT gateway and have NAT gateway's persistent IP address. ### Internet gateway In AWS, Internet Gateway and a persistent IP (elastic IP) is provisioned inside public subnet in each app environemnt for all servers in the VPC to connect to the internet. ### Kubernetes cluster A kubernetes cluster and control plane is provisioned inside each VPC for every environment. This cluster runs the application deployed on the environment. In AWS, AWS Elastic Kubernetes Service (EKS) is provisioned to ensure AWS managas the configure and uptime of Kubernetes control plane. ### Compute servers To run your application's containers, compute servers are provisioned and attached to the kubernetes clusters as Nodes. In AWS, EC2 servers are provisioned. Count and type of EC2 servers depends on the environment template chosen to create the environment. Any type of EC2 servers [supported by AWS](https://aws.amazon.com/ec2/instance-types/) can be provisioned. Also, EBS Volumes are attached by default to each of these EC2 servers. But, the applications deployed on Kubernetes cluster (your app) will dynamically create volumes matching your storage specifications declared in Helm chart. ## Kubernetes companion deployments ### Prometheus Open source [Prometheus](https://prometheus.io/) is installed and pre-configured by LocalOps in an Environment to record system metrics of the compute nodes. ### Loki Open source [Loki](https://grafana.com/oss/loki/) is installed and pre-configured by LocalOps in an environment to record logs of your application. ### Grafana Open source [Grafana](https://grafana.com/oss/grafana/) is installed and pre-configured by LocalOps in an app environment to store logs and metrics from your environment and let you visualise them in a single dashboard. ## Your services Your code is run as Services. > [!NOTE] > > If you have more questions, please reach out to us at [support@localops.co](mailto:support@localops.co). Or schedule a [deep dive > session](https://go.localops.co/tour) with us anytime over zoom. # Alerts Source: https://docs.localops.co/environment/monitoring/alerts Every environment comes pre-installed with open source Grafana. * Logs & metrics from your app and environment are recorded by Loki & Prometheus and sent to the corresponding Grafana installation running within the same cluster. * Each Grafana installation gets its own domain and URL so that your team can login and configure views, dashboards and alerting as needed for that specific environment. > [!NOTE] > > Grafana has an extensive guide on how to configure Alerting. [Please refer to their > guide](https://grafana.com/docs/grafana/latest/alerting/) to learn more and configure them as you see fit for your > team and for each environment. You can login to an environment's Grafana dashboard from Monitoring tab of the environment, from within LocalOps dashboard. # Crashes Source: https://docs.localops.co/environment/monitoring/crashes We don't recommend crashes to be recorded and seen at an environment level as it will be too fragmented for your team to manage. So you can sign up for a crash reporting service and use it as your central store for recording crashes. [Sentry](https://sentry.io/welcome/) is the most popular choice today. There are also other prominent tools like [BugSnag](https://www.bugsnag.com/) which you can explore and decide if they will be a better fit for your team. You can sign up for an account in one of these services and embed their SDK in Front-end and Back-end codebases to record crashes. Every unique application you make is usually modeled as a project in these crash reporting tools and crashes are recorded with environment tag. For environment tag, you can use name like *production*, *staging*, *customer-1*, *customer-4*, etc., to identify which environment saw the crash. This tag name can be seen on your Grafana dashboard, which you can use to query the logs. # Logs Source: https://docs.localops.co/environment/monitoring/logs Every environment comes pre-installed with its own instance of open source [Loki](https://grafana.com/oss/loki/) and [Grafana](https://grafana.com/oss/). Grafana will be running on its own URL for each environment and must be used to see all logs collected from your environment. *Grafana is simple to use yet very powerful in how you can customize the setup for yourself.* ### Print logs Your application should be printing logs to STDOUT or STDERR. These logs will be collected automatically by pre-installed Loki and kept available for you to view inside Grafana dashboard. ### See logs Grafana dashboard can be opened from Monitoring tab, in Environment page. Logs are collected and kept organised under a Kubernetes namespace. Your application is hosted in a specific Kubernetes namespace using which you can filter and see logs under Explore section. ### Tail logs from your terminal Grafana is the place to search and correlate logs across your environment. When you just want to watch one service as it runs - during a deploy, or while reproducing a bug - `ops logs` streams the same output straight to your terminal: ```sh theme={null} ops logs --env staging --svc api ``` `--env` and `--svc` take the environment and service **names** shown in your dashboard, or their ids. The stream stays open and prints new lines as they arrive - press `Ctrl-C` to stop. Every ready pod of the service is read at once, and each line is prefixed with the pod it came from so you can tell replicas apart: ``` [api-7d9f8b6c4-2xk9p] GET /health 200 [api-7d9f8b6c4-mn4vt] GET /orders 201 ``` The flags you will reach for most often: | Flag | Default | Description | | - | - | - | | `-n, --tail` | `100` | Number of recent lines to show. `0` shows everything Loki holds | | `-S, --since` | - | Only show logs newer than this, e.g. `15m` or `2h` | | `-T, --timestamps` | `false` | Prefix each line with its timestamp | | `-f, --follow` | `true` | Pass `--follow=false` for a snapshot that prints and exits | ```sh theme={null} ops logs --env staging --svc api --tail 500 --timestamps ops logs --env staging --svc api --since 15m ops logs --env staging --svc api --follow=false ``` Not sure of the exact command? Open your service and go to its **Logs** tab. It walks you through installing the CLI and logging in, then gives you an `ops logs` command already scoped to that environment and service, ready to copy. Already set up? Tick **I've already installed the CLI and logged in** to see just the command. ![Logs tab](https://mintcdn.com/localops/adl8GZ39ThsoA-bV/changelogs/images/2026/logs-tab-oct-27-26.png?fit=max\&auto=format\&n=adl8GZ39ThsoA-bV\&q=85\&s=8a62aae56fbbc9cc4c3142f24cb19af3) Don't have the CLI yet? Install it on [macOS](/cli/install-macos), [Linux](/cli/install-linux) or [Windows](/cli/install-windows), then run `ops login`. See [CLI usage](/cli/usage#stream-logs-from-a-service) for the full set of options, including `-i` to pick a single pod. ### Custom dashboards Grafana installation in each environment comes with pre-built dashboards to see infrastructure/system metrics. You can create new dashboards to see logs from different deployments/services in your application as needed. > [!NOTE] > > See [Grafana docs](https://grafana.com/docs/grafana/latest/?pg=oss-graf\&plcmt=resources) to learn more # Metrics Source: https://docs.localops.co/environment/monitoring/metrics Every environment comes pre-installed with open source [Prometheus](https://prometheus.io/) and [Grafana](https://grafana.com/oss/). Grafana will be running on its own URL for each environment and must be used to see all metrics collected from your environment. *Grafana is simple to use yet very powerful in how you can customize the setup for yourself.* ### Recording metrics CPU, memory, disk and network metrics from each node running your app, inside kubernetes, is recorded by prometheus and sent to Grafana for your visibility. ### See metrics Grafana installation of the specific environment can be opened from Monitoring tab of Environment page. Inside Grafana, you can group and see CPU/Memory/Disk/Network metrics by: * node * pod * deployment * service * namespace ### In-built dashboards Grafana installation in each environment comes with a lot of pre-built dashboards to see infrastructure/system metrics. You can star the frequently visited ones for convenience. ### Custom dashboards You can create new dashboards within the specific Grafana installation to see metrics from different nodes in your application as needed. > [!NOTE] > > See [Grafana docs](https://grafana.com/docs/grafana/latest/?pg=oss-graf\&plcmt=resources) to learn more # Protected environments Source: https://docs.localops.co/environment/protected-environments Limit an environment, such as production, to the people you choose, with a role of its own By default an environment belongs to the whole project. Everyone in the project can see it, with their [project role](/team/understanding-roles#project-roles). **Protecting** an environment changes that. Only these people can see a protected environment: * Owners and Admins with full access to the project * The people you add to the environment Everyone else - including people with the Member role in the project - loses access to it until they're added. Use it for environments such as production, where only a few people should deploy or read secrets. ## What changes for people who aren't added A protected environment is hidden from them completely: * It isn't listed under the project's environments. * Its deployments and operations aren't listed either. * Opening its link shows **Environment not found**. * They can't pick it as a source for **Import from environment**. * The CLI can't reach it. Owners and Admins who are [restricted](/team/owner-admin-restrictions) in the project are treated like everyone else here: they need to be added. ## Environment roles Everyone you add gets an **environment role** - Read-only, Maintainer or Member. Inside that environment it replaces their project role, and it can be higher or lower than it. For example, a project Maintainer can be given Read-only on production, and a project Read-only can be given Maintainer on a protected staging environment. What each role can do there is the same as in the [roles tables](/team/understanding-roles#permissions-in-detail): deploying needs Maintainer, secret values need Member, and so on. The [CLI](/cli/usage#who-can-run-which-command) uses the environment role too. Only people who are already in the project can be added. To give someone access to a protected environment, [add them to the project](/team/project-members) first. ## Protect an environment You need the Member role in the project, or full access. 1. Open the environment. 2. Click **Protect** in the header. 3. Read the confirmation and click **Protect**. If you're not an Owner or Admin with full access, you're added to the environment with your current project role, so you keep access. Protected environments show a **Protected** badge, in the environment header and next to its name in the environments list. > [!WARNING] > > Everyone without full access loses the environment as soon as it's protected - their open pages stop working and the > CLI can no longer reach it. Add the people who need it right after protecting. ## Add people and set their role Open the environment's **Members** tab. It only appears on protected environments. The list shows everyone who could have access - the project's members and the organization's Owners and Admins: | Column | What it shows | | - | - | | **User** | Name and email, with an **Org owner** or **Org admin** badge for Owners and Admins | | **Project role** | Their role in the project | | **Environment role** | The role set for them in this environment, or a dash if they don't have one | | **Access here** | What they can do here, with where it comes from underneath: **Full access (owner/admin)**, **Set for this environment**, **Restricted** or **No access** | To add someone, click **⋯** on their row, choose **Add to environment**, pick a role and click **Add**. To change a role, choose **Change environment role**, pick the new role and click **Save**. To take someone out, choose **Remove from environment**. They can no longer see the environment. You need the Member role in the environment, or full access, to add, change or remove people. ## Owners and Admins in a protected environment Owners and Admins with full access don't need adding. Setting an environment role on one of them is a **restriction** - it lowers their access in this environment only, following the [restriction rules](/team/owner-admin-restrictions): * Anyone can restrict themselves, to any role, and lift their own restriction. * Restricting another Owner or Admin needs the Member role in the environment, or full access. If they're already restricted, their role can only be lowered. * Only the person themselves or an Owner or Admin with full access can lift a restriction, with **Lift restriction**. ## Unprotect an environment You need the Member role in the environment, or full access. 1. Open the environment. 2. Click **Unprotect** in the header. 3. Confirm with **Unprotect**. > [!WARNING] > > Unprotecting deletes every environment role in it, including Owner and Admin restrictions. Everyone goes back to their > project role. If you protect the environment again later, you have to add people again. ## Who can do what | Action | Needs | | - | - | | See a protected environment | Full access, or an environment role | | Protect an environment | Member role in the project, or full access | | Unprotect an environment | Member role in the environment, or full access | | Add, change or remove people | Member role in the environment, or full access | | Restrict yourself, or lift your own restriction | Any Owner or Admin | | Restrict another Owner or Admin | Member role in the environment, or full access | | Lift another Owner's or Admin's restriction | Full access | **Full access** means an Owner or Admin who isn't restricted in the project or the environment. # Environment security controls on AWS Source: https://docs.localops.co/environment/security What "production grade" means in a LocalOps environment on AWS - isolation, keyless access, network, encryption, least-privilege IAM, secrets, backups and audit logging, all enabled by default. When we say a LocalOps environment is *production grade*, we mean a specific set of security controls is switched on for every cluster we create, from the moment it is created. You don't configure them, and your services don't need code changes to benefit from them. This page walks through each of them for environments on AWS. > [!NOTE] > > This guide covers AWS environments. For GCP, see [Environment security controls on GCP](/environment/security-gcp). ## Dedicated environment in your account Every environment is its own single-tenant deployment inside your AWS account. It gets its own VPC and its own EKS cluster. No compute, network or Kubernetes control plane is shared with any other environment or any other customer. ```mermaid actions={false} theme={null} flowchart LR subgraph acct["Your AWS account"] subgraph p["production"] pv["VPC"] --- pc["EKS cluster"] --- pk["KMS key"] end subgraph s["staging"] sv["VPC"] --- sc["EKS cluster"] --- sk["KMS key"] end end classDef default fill:transparent,stroke:#888,stroke-width:1px style acct fill:transparent,stroke:#888,stroke-width:1px style p fill:transparent,stroke:#888,stroke-width:1px style s fill:transparent,stroke:#888,stroke-width:1px ``` For each cluster, LocalOps also turns on: * **A customer-managed KMS key per cluster.** EKS encrypts every Kubernetes Secret in etcd with it. Only your account, the provisioning role and the EKS cluster role can use the key. * **Control-plane audit logging.** EKS ships `api`, `audit`, `authenticator`, `controllerManager` and `scheduler` logs to CloudWatch Logs in your account. * **IAM-based cluster access.** Access to the Kubernetes API is managed as IAM principals through EKS access entries, not through hand-edited `aws-auth` entries. Every request to the API server is authenticated with AWS IAM and served over TLS. * **Isolated provisioning state.** Each environment, and each service inside it, is provisioned and tracked independently, so a change to one can never leak into or roll back another. Secret values in provisioning state are encrypted with KMS before they are stored. * **Resource tagging.** Your organisation's tags are applied to every AWS resource, including EC2 instances, volumes and network interfaces, so cost allocation and tag-based policies work out of the box. See [AWS resource tags](/environment/infra-resources/aws). ## Keyless access to your cloud account LocalOps never holds static AWS access keys for your account. When you connect an AWS account, you create an IAM role with a CloudFormation template. LocalOps reaches your account only by exchanging a short-lived token from its OIDC identity provider for temporary credentials on that role. ```mermaid actions={false} theme={null} sequenceDiagram participant L as LocalOps participant S as AWS STS participant A as Your AWS account L->>S: AssumeRoleWithWebIdentity (short-lived OIDC token) S-->>L: Temporary credentials (1 hour) L->>A: Provisioning calls, under a named session Note over A: Every call is recorded in your CloudTrail ``` * **Short sessions.** Provisioning sessions last one hour. Token files exist only for the duration of a run and are deleted afterwards. * **Pinned trust.** The role trusts only tokens issued for your connection's client ID, with the `sts.amazonaws.com` audience. A token for another connection can't assume it. * **Fully auditable.** Every call runs under a named STS session and shows up in your CloudTrail. * **Revocable at any time.** Deleting the CloudFormation stack removes the role and cuts off access immediately. ## Network isolation Every environment gets a dedicated VPC with public and private subnets across up to three availability zones. You can pick a [custom CIDR](/environment/create) when creating the environment so it doesn't overlap with networks you plan to peer with. ```mermaid actions={false} theme={null} flowchart TB user["Internet"] -- "HTTPS 443" --> lb subgraph vpc["Environment VPC"] subgraph pub["Public subnets"] lb["Load balancer"] nat["NAT gateway + static IP"] end subgraph priv["Private subnets (no public IPs)"] ing["ingress-nginx"] --> svc["Your services"] svc -- "engine port, from VPC CIDR only" --> db["RDS / ElastiCache / OpenSearch"] end lb --> ing svc --> nat end nat -- "outbound" --> ext["Third-party APIs"] classDef default fill:transparent,stroke:#888,stroke-width:1px style vpc fill:transparent,stroke:#888,stroke-width:1px style pub fill:transparent,stroke:#888,stroke-width:1px style priv fill:transparent,stroke:#888,stroke-width:1px ``` * **Workloads in private subnets.** The EKS control-plane network interfaces, every node group, and RDS, ElastiCache and OpenSearch all sit in private subnets with no public IPs. * **One way in.** Public HTTP(S) traffic enters only through one load balancer in front of the environment's ingress-nginx. Your services are never exposed to the internet directly - only [web services](/environment/services/web) are routed through the ingress. [Internal services](/environment/services/internal), [workers](/environment/services/workers) and [cron jobs](/environment/services/cronjob) stay private. * **Static egress IP.** All outbound traffic leaves through a NAT gateway with an Elastic IP, so partners and SaaS vendors can allowlist your environment. * **Locked-down data services.** Each RDS, ElastiCache and OpenSearch instance gets its own security group that accepts only its engine port, and only from the environment's VPC CIDR. See [Firewall / security groups](#firewall-/-security-groups). * **Databases private by default.** RDS is not publicly accessible unless you ask for it - and even then, its security group still only accepts traffic from the VPC. OpenSearch is VPC-attached unless you explicitly make it public. * **Per-service IP allowlist.** You can restrict a web service to a list of IPs or CIDR ranges, enforced at the ingress. Preview environments inherit the list of the service they preview, so a preview is never more open than the app itself. An invalid entry fails the deploy instead of shipping an unenforced rule. * **Spoof-proof client IPs.** The load balancer passes the real client IP to the ingress over proxy protocol, and only the VPC CIDR is trusted to set it, so `X-Real-IP` and `X-Forwarded-For` can't be forged from the internet. See [Client IP](/environment/services/client-ip). * **DNS record ownership.** When environments share a Route 53 zone, each environment can only update records it owns, so one environment can never rewrite another's. ## Firewall / security groups Security groups are the firewall around each piece of the environment. LocalOps creates them so that only the load balancer accepts traffic from the internet, and everything behind it accepts traffic only from inside the VPC. ```mermaid actions={false} theme={null} flowchart TB inet["Internet"] -- "TCP 80/443" --> lbsg["Load balancer SG
80/443 from anywhere"] lbsg --> eks["EKS cluster and node SGs
(managed by EKS)"] eks -- "engine port only" --> dsg["Data-service SGs
from VPC CIDR only"] classDef default fill:transparent,stroke:#888,stroke-width:1px ``` | Security group | Protects | Inbound allowed | | - | - | - | | Load balancer | Environment's ingress | TCP `80` and `443` from anywhere | | EKS cluster and node groups | Kubernetes control plane, nodes | EKS defaults, nodes in private subnets | | `rds-dep---sg` | RDS PostgreSQL | TCP `5432` from the VPC CIDR | | `rds-dep---sg` | RDS MySQL | TCP `3306` from the VPC CIDR | | `rds-dep---sg` | RDS SQL Server | TCP `1433` from the VPC CIDR | | `cache-dep---sg` | ElastiCache Redis / Valkey | TCP `6379` from the VPC CIDR | | `cache-dep---sg` | ElastiCache Memcached | TCP `11211` from the VPC CIDR | | `opensearch-dep---sg` | OpenSearch (VPC mode) | TCP `443` from the VPC CIDR | * **One group per dependency.** Every database, cache and search domain gets its own security group, opened only on its engine port. Nothing else on the instance is reachable. * **VPC-only, even when public.** An RDS instance marked publicly accessible still only accepts traffic from the VPC CIDR through its security group. * **Public OpenSearch is gated differently.** In public mode, OpenSearch gets no security group, and access is gated by HTTPS and fine-grained access control instead. * **Finer filtering at the ingress.** The load balancer is the only group open to the internet. To narrow it further for a web service, use the per-service IP allowlist, enforced at the ingress. * **Outbound is open.** Every group allows all outbound traffic, which leaves the VPC through the NAT gateway's static IP. > [!TIP] > > Connecting environments across VPCs, for example with VPC peering, means adding inbound rules for the peer VPC's CIDR > to the security group whose name contains `eks-cluster`. ### Web application firewall with Cloudflare Security groups filter by IP and port. To filter by what's inside a request - SQL injection, bot traffic, layer 7 DDoS - put Cloudflare in front of your web services and use its WAF. Cloudflare has a generous free plan that includes DDoS protection and basic WAF rules, so you can start without paying anything. ```mermaid actions={false} theme={null} flowchart LR user["Users"] --> cf["Cloudflare
(WAF, DDoS, bot rules)"] cf -- "HTTPS" --> lb["Environment load balancer"] lb --> svc["Your web service"] classDef default fill:transparent,stroke:#888,stroke-width:1px ``` 1. [Sign up for Cloudflare](https://dash.cloudflare.com/sign-up) if you don't have an account yet. 2. Add your domain to Cloudflare and set up a [custom domain](/environment/services/custom-domain) for your web service. 3. Turn on the proxy (orange cloud) for that DNS record, so traffic flows through Cloudflare before it reaches your environment. 4. Set Cloudflare's SSL/TLS mode to **Full (strict)**. Your service already has a valid certificate, so traffic stays encrypted all the way to the environment. 5. Enable the WAF managed rules, rate limiting and bot protection you need in the Cloudflare dashboard. 6. Add [Cloudflare's IP ranges](https://www.cloudflare.com/ips/) to the web service's IP allowlist, so nobody can skip the WAF by calling your environment's load balancer directly. Behind Cloudflare, read the visitor's IP from the `CF-Connecting-IP` header. See [Client IP](/environment/services/client-ip). ## Encryption in transit Every web service is served over HTTPS with its own certificate, issued and renewed automatically. ```mermaid actions={false} theme={null} flowchart LR c["Client"] -- "TLS" --> i["ingress-nginx"] i --> s["Your service"] cm["cert-manager"] -. "issues and renews (Let's Encrypt)" .-> i classDef default fill:transparent,stroke:#888,stroke-width:1px ``` * **Automatic certificates.** Each web service gets a Let's Encrypt certificate for its default subdomain, and for every [custom domain](/environment/services/custom-domain) as soon as it is activated. The environment's Grafana host gets one too. * **Self-renewing.** Certificates renew automatically about 30 days before they expire and are swapped in without a restart. Nobody rotates a certificate by hand, and nothing expires silently. * **No shared wildcard, no DNS credentials.** Domain ownership is proven with HTTP-01 challenges served by the environment's own ingress. Each service has its own certificate and private key, stored as a Kubernetes Secret and encrypted with the environment's KMS key. * **End-to-end TLS when you need it.** With [`ssl_passthrough`](/environment/services/ops-json#ssl-passthrough), the ingress hands the TLS stream to your app unterminated, for apps that must hold their own certificate. * **TLS to managed services.** OpenSearch enforces HTTPS with TLS 1.2 or newer, with node-to-node encryption on. All provisioning calls to AWS, EKS and Kubernetes APIs go over TLS. ## Encryption at rest Data written by your services and by LocalOps is encrypted at rest using AWS-native encryption, with no application changes. | What | How it's encrypted | | - | - | | Persistent volumes (PVCs) | Default `gp3-encrypted` StorageClass - every volume is encrypted EBS | | Kubernetes Secrets | Envelope-encrypted with the environment's own customer-managed KMS key | | RDS databases | Storage encryption on every engine that supports it | | OpenSearch domains | Encryption at rest enabled | | S3 buckets | SSE-S3, with Block Public Access on and ACLs disabled | | SQS queues | SSE-SQS | | Environment and service secrets | SSM Parameter Store `SecureString`, encrypted with KMS, in your account | | Database master credentials | AWS Secrets Manager | | Backup bucket | SSE-S3 (AES-256) | ## Least-privilege IAM Every component in the environment gets its own IAM role, trusted only by the one thing that needs it. ```mermaid actions={false} theme={null} flowchart LR oidc["Cluster OIDC provider"] oidc --> app["App role
(your services)"] oidc --> ebs["EBS CSI role"] oidc --> gr["Grafana role
(read-only CloudWatch)"] oidc --> dns["external-dns role"] oidc --> vel["Backup role"] app --> s3["S3 bucket ARN"] app --> q["SQS queue ARN"] app --> sec["DB secret ARN"] classDef default fill:transparent,stroke:#888,stroke-width:1px ``` * **Workload identity everywhere.** Your services and every platform add-on use IAM Roles for Service Accounts (IRSA). Nothing borrows the node's role for cloud access. Each role's trust policy pins the exact namespace and service account that may assume it. * **No static keys in your apps.** The AWS SDK picks up temporary credentials automatically. There are no access keys to rotate, leak or manage. * **App role starts empty.** Your services' role has no permissions at creation. Each dependency you declare in [`ops.json`](/environment/services/ops-json) attaches a policy scoped to that one resource's ARN. * **Scoped platform roles.** The cluster role is trusted only by EKS, and the node role only by EC2. The Grafana role is read-only and limited to the environment's region. The backup role can only touch this environment's backup bucket. What each declared dependency grants: | Dependency | Access granted to your services | | - | - | | S3 bucket | Bucket listing and object read/write on that bucket only | | SQS queue | Send, receive and delete messages on that queue only | | SNS topic | Publish and subscribe on that topic only | | RDS instance | Read its master-credential secret only | | OpenSearch domain | Read its master-user secret, and HTTP access to that domain only | | ElastiCache cluster | No IAM access - reachable over the network from inside the VPC only | > [!NOTE] > > All services in an environment share the environment's app role, so the environment is the IAM isolation boundary. Put > workloads that must not share cloud access in separate environments. ## Kubernetes access control ```mermaid actions={false} theme={null} flowchart TB subgraph cluster["EKS cluster"] plat["Platform namespaces
ingress-nginx
cert-manager
monitoring
external-dns
velero"] appns["app-services
Your pods"] helmns["ns-<helm service>
Helm service pods"] end classDef default fill:transparent,stroke:#888,stroke-width:1px style cluster fill:transparent,stroke:#888,stroke-width:1px ``` * **Your pods can't read the cluster.** The service account your pods run as can only manage leader-election leases. Pods can't list or read Secrets, or any other object, through the Kubernetes API. * **Platform components are separated.** ingress-nginx, cert-manager, monitoring, external-dns and backups each run in their own namespace, apart from your workloads. * **Helm services get their own namespace.** Every [Helm chart service](/environment/services/helm-charts) installs into its own namespace with its own image pull secret, app secret and service account. * **Scoped console access.** Console access to the cluster goes through a dedicated IAM role limited to that one cluster, with short-lived credentials. ## Compute and workloads * **Managed node groups.** Nodes run in EKS managed node groups on Amazon Linux 2023 (x86\_64 or arm64), or your own AMI, on on-demand or spot capacity. * **Workload placement.** Every service is pinned to the node group you choose, so sensitive workloads can run on their own nodes. * **No privileged containers by default.** A container runs privileged only if its [`ops.json`](/environment/services/ops-json#privileged-containers) asks for it, an admin has allowed privileged pods on the cloud connection, and the service isn't a preview. Otherwise it deploys unprivileged and the refusal is noted in the deploy log. * **Isolated services.** Each service owns its own Kubernetes objects, certificate, secrets and cloud dependencies, and is deployed independently. A failed or rolled-back deploy of one service never touches another. * **Safe rollouts.** Deploys wait for the new version to become ready before completing. Helm releases are atomic and clean up after themselves on failure. Identity fields of databases and search domains, like engine and database name, are locked against accidental replacement. * **Resource limits and health checks.** CPU and memory requests and limits are set per service, and [health checks](/environment/services/ops-json) restart unhealthy containers. ## Secrets handling ```mermaid actions={false} theme={null} flowchart LR con["LocalOps console"] --> ssm["SSM SecureString
(your account, KMS)"] ssm --> ks["Kubernetes Secret
(KMS-encrypted in etcd)"] ks --> env["Env vars in your container"] classDef default fill:transparent,stroke:#888,stroke-width:1px ``` * **Stored in your account.** [Secrets](/environment/services/secrets) you add in the console are stored as SSM Parameter Store `SecureString` parameters in your AWS account, encrypted with KMS. * **Never in the pod spec.** Values reach your container as environment variables through Kubernetes Secret references. They are never written into the pod definition. * **Scoped per service.** A pod receives only its own service's secrets, environment-wide shared secrets, and secrets of services it explicitly imports. It never sees another service's secrets implicitly. * **Generated credentials stay secret.** Database passwords are never logged. They are read from Secrets Manager and delivered through a per-service Secret. RDS-managed passwords are rotated by AWS. * **Registry credentials per namespace.** Image pull credentials live as a Secret in each namespace that needs them. ## Backups and recovery ```mermaid actions={false} theme={null} flowchart LR pv["Persistent volumes"] -- "EBS snapshots" --> bk["Per-environment backup bucket
(private, encrypted)"] rds["RDS"] -- "30-day automated backups" --> snap["Final snapshot on delete"] ec["ElastiCache"] -- "30-day snapshots" --> snap classDef default fill:transparent,stroke:#888,stroke-width:1px ``` * **Cluster and volume backups.** Every environment has a backup tool installed with its own private, encrypted S3 bucket and EBS volume snapshots. Snapshots are retained, and the bucket outlives the environment. See [Backup & restore](/environment/backups-restore). * **RDS.** 30-day automated backups, enhanced monitoring, and a final snapshot before deletion. Multi-AZ is available. * **ElastiCache.** 30-day snapshot retention and a final snapshot before deletion. * **OpenSearch.** Three data nodes across availability zones by default. Two-node clusters without dedicated masters are refused, since they can't keep quorum. ## Logs, metrics and audit * **Application logs.** Container logs are collected into an in-cluster Loki with 30-day retention. See [Logs](/environment/monitoring/logs). * **Metrics.** An in-cluster Prometheus keeps 30 days of metrics. Grafana is served over TLS on the environment's monitoring host, behind a login. See [Metrics](/environment/monitoring/metrics). * **Kubernetes audit logs.** EKS control-plane logs, including the audit log, go to CloudWatch Logs in your account. * **OpenSearch logs.** Slow, application and audit logs are published to CloudWatch with 30-day retention. * **Cloud API audit.** Every action LocalOps takes in your account runs under a named session and is recorded by your CloudTrail. Keeping CloudTrail enabled is up to your AWS organisation. > [!NOTE] > > [Preview environments](/use-cases/ephemeral) get the same cluster-level controls, with a few deliberate differences to > keep them cheap and disposable: preview services never run privileged, and preview RDS databases skip storage > encryption and backups. For who owns what, see [Shared responsibilities](/environment/shared-responsibilities). # Environment security controls on GCP Source: https://docs.localops.co/environment/security-gcp What "production grade" means in a LocalOps environment on GCP - isolation, keyless access, network, encryption, least-privilege IAM, secrets, backups and audit logging, all enabled by default. When we say a LocalOps environment is *production grade*, we mean a specific set of security controls is switched on for every cluster we create, from the moment it is created. You don't configure them, and your services don't need code changes to benefit from them. This page walks through each of them for environments on Google Cloud. > [!NOTE] > > This guide covers GCP environments. For AWS, see [Environment security controls on AWS](/environment/security). ## Dedicated environment in your project Every environment is its own single-tenant deployment inside your GCP project. It gets its own VPC network and its own GKE cluster. No compute, network or Kubernetes control plane is shared with any other environment or any other customer. ```mermaid actions={false} theme={null} flowchart LR subgraph proj["Your GCP project"] subgraph p["production"] pv["VPC network"] --- pc["GKE cluster"] end subgraph s["staging"] sv["VPC network"] --- sc["GKE cluster"] end end classDef default fill:transparent,stroke:#888,stroke-width:1px style proj fill:transparent,stroke:#888,stroke-width:1px style p fill:transparent,stroke:#888,stroke-width:1px style s fill:transparent,stroke:#888,stroke-width:1px ``` For each cluster, LocalOps also turns on: * **A highly available control plane.** Clusters are regional, so GKE runs the Kubernetes control plane across multiple zones in the region. * **Workload Identity.** Pods get Google credentials only through a Kubernetes service account explicitly bound to a Google service account. No service account keys are created or mounted anywhere. * **IAM-based cluster access.** Every request to the Kubernetes API server is authenticated with Google IAM and served over TLS. No static cluster credentials are issued. * **Controlled upgrades.** The Kubernetes version changes only through a deliberate, reviewed rollout, never on its own. Node auto-repair stays on, so unhealthy nodes are still replaced automatically. * **Isolated provisioning state.** Each environment, and each service inside it, is provisioned and tracked independently, so a change to one can never leak into or roll back another. Secret values in provisioning state are encrypted with KMS before they are stored. * **Resource labels.** Your organisation's tags are applied as GCP labels to every resource that supports them, including the GKE cluster, node VMs and Cloud SQL instances, so cost allocation and label-based policies work out of the box. ## Keyless access to your cloud project LocalOps never holds a service account key for your project. When you [connect a GCP project](/accounts/gcp), you create a Workload Identity Federation pool and provider that trust LocalOps, plus a service account LocalOps may impersonate. Each provisioning run exchanges a short-lived LocalOps token at Google STS and impersonates that service account. ```mermaid actions={false} theme={null} sequenceDiagram participant L as LocalOps participant S as Google STS participant P as Your GCP project L->>S: Exchange short-lived OIDC token (Workload Identity Federation) S-->>L: Short-lived access token (1 hour) L->>P: Provisioning calls, as the connection service account Note over P: Every call is recorded in your Cloud Audit Logs ``` * **Short sessions.** Access tokens last one hour and are minted fresh for every provisioning run. Credential files are written with owner-only permissions for the duration of the run and deleted afterwards. * **Audience-pinned tokens.** Tokens LocalOps issues for GCP carry a dedicated audience, and your federation provider accepts only tokens for your connection. * **Fully auditable.** Every call runs as the connection service account and shows up in your project's Cloud Audit Logs. * **Revocable at any time.** Deleting the federation provider or the service account cuts off access immediately. * **Only the APIs it needs.** LocalOps enables only the APIs the platform uses (Compute, GKE, Secret Manager, IAM, Service Networking, Cloud Storage, Pub/Sub, Cloud SQL Admin and Memorystore), and never disables them on teardown, so other workloads in your project aren't affected. ## Network isolation Every environment gets its own custom-mode VPC network - no auto-created subnets - with one regional subnet for nodes. Pods and Services use separate VPC-native ranges. You can pick a [custom CIDR](/environment/create) when creating the environment so it doesn't overlap with networks you plan to peer with. ```mermaid actions={false} theme={null} flowchart TB user["Internet"] -- "HTTPS 443" --> lb["Regional load balancer"] subgraph vpc["Environment VPC network"] subgraph nodes["Node subnet (no external IPs)"] ing["ingress-nginx"] --> svc["Your services"] end lb --> ing svc -- "private IP" --> db["Cloud SQL / Memorystore
(Private Service Access)"] svc --> nat["Cloud NAT"] end nat -- "outbound" --> ext["Third-party APIs"] svc -. "Private Google Access" .-> gapi["Google APIs"] classDef default fill:transparent,stroke:#888,stroke-width:1px style vpc fill:transparent,stroke:#888,stroke-width:1px style nodes fill:transparent,stroke:#888,stroke-width:1px ``` * **Private nodes.** Node VMs have no external IP addresses and can't be reached directly from the internet. * **Private Google Access.** Nodes reach Google APIs - container images, Secret Manager, Cloud Storage - over internal IPs, without any public address. * **One way in.** Public HTTP(S) traffic enters only through one regional load balancer in front of the environment's ingress-nginx. Your services are never exposed to the internet directly - only [web services](/environment/services/web) are routed through the ingress. [Internal services](/environment/services/internal), [workers](/environment/services/workers) and [cron jobs](/environment/services/cronjob) stay private. * **Controlled egress.** All outbound internet traffic leaves through a regional Cloud NAT on a dedicated Cloud Router. * **Private data services.** Cloud SQL and Memorystore are attached through Private Service Access on a reserved internal range peered to the environment's VPC. Cloud SQL instances have no public IP. * **Per-service IP allowlist.** You can restrict a web service to a list of IPs or CIDR ranges, enforced at the ingress. Preview environments inherit the list of the service they preview, so a preview is never more open than the app itself. An invalid entry fails the deploy instead of shipping an unenforced rule. * **Spoof-proof client IPs.** The load balancer passes the real client IP through, and the ingress ignores inbound `X-Forwarded-For` headers, so a client can't forge its address to slip past an IP allowlist. See [Client IP](/environment/services/client-ip). ## Firewall rules The environment's VPC denies all inbound traffic by default. The only inbound rules are the ones GKE manages for its own cluster, and LocalOps opens no additional ports. ```mermaid actions={false} theme={null} flowchart TB inet["Internet"] -- "TCP 80/443" --> lb["Load balancer rule
80/443 to ingress-nginx only"] lb --> nodes["GKE-managed rules
control plane and in-cluster traffic"] nodes -- "private IP only" --> data["Cloud SQL / Memorystore
no public IP"] classDef default fill:transparent,stroke:#888,stroke-width:1px ``` | Rule | Allows | Source | | - | - | - | | VPC implied rule | Deny all inbound, allow all outbound | - | | GKE control plane (`gke--*-master`) | Control plane to nodes | Control plane range | | GKE in-cluster (`gke--*-vms`, `-all`) | Node to node, pod to pod | Node subnet and pod range | | Load balancer (`k8s-fw-`) | TCP `80` and `443` to ingress-nginx | Anywhere | | Load balancer health checks | Health probes to ingress-nginx | Google health-check ranges | | Cloud SQL / Memorystore | Engine port | Environment VPC, over peering | * **Deny by default.** Anything not explicitly allowed above is blocked. * **One public entry point.** The load balancer rule is the only one open to the internet. To narrow it further for a web service, use the per-service IP allowlist, enforced at the ingress. * **No stale rules.** Load balancer firewall rules GKE creates outside the cluster are removed when the environment is deleted, scoped to that environment's VPC. > [!TIP] > > Connecting environments across VPCs, for example with VPC Network Peering, means adding an ingress firewall rule for > the peer network's CIDR on the ports your services need. ### Web application firewall with Cloudflare Firewall rules filter by IP and port. To filter by what's inside a request - SQL injection, bot traffic, layer 7 DDoS - put Cloudflare in front of your web services and use its WAF. Cloudflare has a generous free plan that includes DDoS protection and basic WAF rules, so you can start without paying anything. ```mermaid actions={false} theme={null} flowchart LR user["Users"] --> cf["Cloudflare
(WAF, DDoS, bot rules)"] cf -- "HTTPS" --> lb["Environment load balancer"] lb --> svc["Your web service"] classDef default fill:transparent,stroke:#888,stroke-width:1px ``` 1. [Sign up for Cloudflare](https://dash.cloudflare.com/sign-up) if you don't have an account yet. 2. Add your domain to Cloudflare and set up a [custom domain](/environment/services/custom-domain) for your web service. 3. Turn on the proxy (orange cloud) for that DNS record, so traffic flows through Cloudflare before it reaches your environment. 4. Set Cloudflare's SSL/TLS mode to **Full (strict)**. Your service already has a valid certificate, so traffic stays encrypted all the way to the environment. 5. Enable the WAF managed rules, rate limiting and bot protection you need in the Cloudflare dashboard. 6. Add [Cloudflare's IP ranges](https://www.cloudflare.com/ips/) to the web service's IP allowlist, so nobody can skip the WAF by calling your environment's load balancer directly. Behind Cloudflare, read the visitor's IP from the `CF-Connecting-IP` header. See [Client IP](/environment/services/client-ip). ## Encryption in transit Every web service is served over HTTPS with its own certificate, issued and renewed automatically. ```mermaid actions={false} theme={null} flowchart LR c["Client"] -- "TLS" --> i["ingress-nginx"] i --> s["Your service"] cm["cert-manager"] -. "issues and renews (Let's Encrypt)" .-> i classDef default fill:transparent,stroke:#888,stroke-width:1px ``` * **Automatic certificates.** Each web service gets a Let's Encrypt certificate for its default subdomain, and for every [custom domain](/environment/services/custom-domain) as soon as it is activated. The environment's Grafana host gets one too. * **Self-renewing.** Certificates renew automatically about 30 days before they expire and are swapped in without a restart. Nobody rotates a certificate by hand, and nothing expires silently. * **No shared wildcard, no DNS credentials.** Domain ownership is proven with HTTP-01 challenges served by the environment's own ingress. Each service has its own certificate and private key, stored as a Kubernetes Secret and encrypted at rest by GKE. * **End-to-end TLS when you need it.** With [`ssl_passthrough`](/environment/services/ops-json#ssl-passthrough), the ingress hands the TLS stream to your app unterminated, for apps that must hold their own certificate. * **TLS to cloud APIs.** All provisioning calls to Google Cloud and Kubernetes APIs go over TLS. ## Encryption at rest Data written by your services and by LocalOps is encrypted at rest by Google, with no application changes. | What | How it's encrypted | | - | - | | Persistent volumes (PVCs) | Persistent Disks, encrypted with AES-256 by Google | | Node boot disks | Encrypted by Google | | Kubernetes Secrets | Encrypted at rest by GKE along with the rest of cluster state | | Cloud SQL databases | Storage and automated backups encrypted by Google | | Memorystore | Data and snapshots encrypted by Google | | Cloud Storage buckets | Encrypted by Google, with uniform bucket-level access - IAM only, no ACLs | | Pub/Sub | Messages encrypted by Google | | Environment and service secrets | Secret Manager in your project, encrypted at rest and replicated | | Database credentials | Generated by LocalOps and stored in Secret Manager in your project | | Backup bucket | Encrypted by Google, with uniform bucket-level access and public access prevention | ## Least-privilege IAM Every component in the environment that needs Google access gets its own Google service account, usable only by the one Kubernetes service account that needs it. ```mermaid actions={false} theme={null} flowchart LR wi["Workload Identity"] wi --> app["App service account
(your services)"] wi --> vel["Backup service account"] wi --> gr["Grafana service account
(read-only monitoring)"] app --> gcs["Cloud Storage bucket"] app --> ps["Pub/Sub topic / subscription"] classDef default fill:transparent,stroke:#888,stroke-width:1px ``` * **Workload Identity everywhere.** Each Google service account is bound to exactly one namespace and Kubernetes service account. No service account keys exist. * **Node identity is hidden from pods.** Node pools run the GKE metadata server, so pods receive only their own Workload Identity credentials and can't read the node's identity. * **App service account starts empty.** Your services' Google service account has no roles at creation. Each dependency you declare in [`ops.json`](/environment/services/ops-json) grants a role on that one resource. * **Scoped platform accounts.** The backup service account can only touch this environment's backup bucket, and uses a custom role with just the eight disk and snapshot permissions it needs. The Grafana service account is read-only. What each declared dependency grants: | Dependency | Access granted to your services | | - | - | | Cloud Storage bucket | Object read/write on that bucket only | | Pub/Sub topic | Publish and view on that topic only | | Pub/Sub subscription | Subscribe on that subscription only | | Cloud SQL | No IAM access - reached over a private IP with a password | | Memorystore | No IAM access - reachable over a private IP from inside the VPC only | > [!NOTE] > > All services in an environment share the environment's app service account, so the environment is the IAM isolation > boundary. Put workloads that must not share cloud access in separate environments. ## Kubernetes access control ```mermaid actions={false} theme={null} flowchart TB subgraph cluster["GKE cluster"] plat["Platform namespaces
ingress-nginx
cert-manager
monitoring
velero"] appns["app-services
Your pods"] helmns["ns-<helm service>
Helm service pods"] end classDef default fill:transparent,stroke:#888,stroke-width:1px style cluster fill:transparent,stroke:#888,stroke-width:1px ``` * **IAM-authenticated cluster access.** Every call to the Kubernetes API is authenticated with Google IAM using freshly minted short-lived tokens. LocalOps stores no long-lived cluster credentials. * **Your pods can't read the cluster.** The service account your pods run as can only manage leader-election leases. Pods can't list or read Secrets, or any other object, through the Kubernetes API. * **Platform components are separated.** ingress-nginx, cert-manager, monitoring and backups each run in their own namespace, apart from your workloads. * **Helm services get their own namespace.** Every [Helm chart service](/environment/services/helm-charts) installs into its own namespace with its own image pull secret, app secret, service account and Workload Identity binding. ## Compute and workloads * **GKE node pools.** Nodes run on GKE's Container-Optimized OS for Linux, with optional Windows Server pools that only Windows workloads can land on. On-demand or Spot VMs, with autoscaling within the bounds you set. * **Node auto-repair.** GKE automatically recreates nodes that fail health checks. * **Workload placement.** Every service is pinned to the node pool you choose, so sensitive workloads can run on their own nodes. * **No privileged containers by default.** A container runs privileged only if its [`ops.json`](/environment/services/ops-json#privileged-containers) asks for it, an admin has allowed privileged pods on the cloud connection, and the service isn't a preview. Otherwise it deploys unprivileged and the refusal is noted in the deploy log. * **Isolated services.** Each service owns its own Kubernetes objects, certificate, secrets and cloud dependencies, and is deployed independently. A failed or rolled-back deploy of one service never touches another. * **Safe rollouts.** Deploys wait for the new version to become ready before completing. Helm releases are atomic and clean up after themselves on failure. Identity fields of databases, like version, database name and username, are locked against accidental replacement. * **Resource limits and health checks.** CPU and memory requests and limits are set per service, and [health checks](/environment/services/ops-json) restart unhealthy containers. ## Secrets handling ```mermaid actions={false} theme={null} flowchart LR con["LocalOps console"] --> sm["Secret Manager
(your project)"] sm --> ks["Kubernetes Secret
(encrypted at rest by GKE)"] ks --> env["Env vars in your container"] classDef default fill:transparent,stroke:#888,stroke-width:1px ``` * **Stored in your project.** [Secrets](/environment/services/secrets) you add in the console are stored in Secret Manager in your GCP project. * **Never in the pod spec.** Values reach your container as environment variables through Kubernetes Secret references. They are never written into the pod definition. * **Scoped per service.** A pod receives only its own service's secrets, environment-wide shared secrets, and secrets of services it explicitly imports. It never sees another service's secrets implicitly. * **Generated credentials stay secret.** Database passwords are never logged. They are stored in Secret Manager and delivered through a per-service Secret. * **Registry credentials per namespace.** Image pull credentials live as a Secret in each namespace that needs them. ## Backups and recovery ```mermaid actions={false} theme={null} flowchart LR pv["Persistent volumes"] -- "Persistent Disk snapshots" --> bk["Per-environment backup bucket
(private, encrypted)"] sql["Cloud SQL"] -- "daily backups, 30 retained" --> sb["Automated backups"] ms["Memorystore"] -- "snapshot every 24 hours" --> rdb["RDB snapshots"] classDef default fill:transparent,stroke:#888,stroke-width:1px ``` * **Cluster and volume backups.** Every environment has a backup tool installed with its own private Cloud Storage bucket and Persistent Disk snapshots. Snapshots are retained, and the bucket outlives the environment. See [Backup & restore](/environment/backups-restore). * **Cloud SQL.** Daily automated backups with 30 retained, plus Query Insights. High availability, with a standby in another zone, is available. * **Memorystore.** RDB snapshots every 24 hours. ## Logs, metrics and audit * **Application logs.** Container logs are collected into an in-cluster Loki with 30-day retention. See [Logs](/environment/monitoring/logs). * **Metrics.** An in-cluster Prometheus keeps 30 days of metrics. Grafana is served over TLS on the environment's monitoring host, behind a login, with a read-only Cloud Monitoring data source for managed services. See [Metrics](/environment/monitoring/metrics). * **Cloud API audit.** Every action LocalOps takes in your project runs as the connection service account and is recorded in your Cloud Audit Logs. Admin Activity logs are always on. > [!NOTE] > > [Preview environments](/use-cases/ephemeral) get the same cluster-level controls, with a few deliberate differences to > keep them cheap and disposable: preview services never run privileged, and preview Cloud SQL and Memorystore skip > backups and snapshots. For who owns what, see [Shared responsibilities](/environment/shared-responsibilities). # Autoscaling Source: https://docs.localops.co/environment/services/autoscaling Scale a service's replicas on CPU, memory and time-of-day windows with the autoscaling block in ops.json Most services don't need the same number of containers all day. Traffic peaks in business hours, a queue drains overnight, a batch job floods a worker every Monday morning. Declare an `autoscaling` block in `ops.json` and LocalOps adds and removes replicas for you, between your service's container count and a ceiling you set. This is **horizontal** autoscaling - LocalOps runs more copies of your container, it does not give any single container more CPU or memory. The CPU and memory each container gets stay exactly as you set them for the service, and are what the utilization targets below are measured against. > [!NOTE] > > This page assumes your service already deploys on LocalOps and you have set its CPU and memory requirements. If you > haven't, start with [creating a service](/environment/services/create). ## Enable it The smallest block that works needs a ceiling and one thing to scale on: ```json ops.json theme={null} { "autoscaling": { "max_replicas": 10, "target_cpu": 70 } } ``` That holds average CPU utilization near 70% across your service's pods, adding replicas up to 10 and removing them again as load falls. > [!WARNING] > > `target_cpu` needs your service to have a **minimum CPU** set under the Scaling tab in the LocalOps console. > Utilization is measured as a percentage of what each pod requested, so without a minimum there is no denominator - the > autoscaler has nothing to compare against and never scales. The same applies to `target_memory` and minimum memory. > LocalOps refuses the block and tells you so in the deployment logs rather than installing something that quietly does > nothing. ## Autoscaling arguments | Key | Required | Description | | - | - | - | | `max_replicas` | Yes | The ceiling. Never defaulted, because it is the only thing standing between a runaway request loop and a cloud bill you didn't expect. | | `target_cpu` | No | Average CPU utilization to hold, as a percentage of each pod's CPU request. | | `target_memory` | No | Average memory utilization to hold, as a percentage of each pod's memory request. | | `schedules` | No | Time-of-day windows that hold the service at a floor. See [Time-of-day schedules](/environment/services/autoscaling#time-of-day-schedules). | You must declare at least one of `target_cpu`, `target_memory` or `schedules`. A replica range on its own has nothing driving it, so the service would sit at its floor forever - LocalOps treats that as a mistake rather than a valid way to say "off" and ignores the block. ## Replica range There is no `min_replicas` key. The floor is always your service's **number of containers** - the same count you set when [creating the service](/environment/services/create#number-of-containers) or later under its Scaling tab. That count exists whether or not the service autoscales, so there is exactly one place to set it, and switching autoscaling on never shrinks a running service by surprise. To raise or lower the floor, change the container count. `max_replicas` is capped at the platform limit of `50`. If it is below the service's container count, it is raised to match. > [!NOTE] > > Scaling to zero is not supported. A service with no pods running has nothing to measure utilization on. If you stop a > service (container count `0`), autoscaling is **paused**, not removed - the configuration is kept and applies again > once the count is raised above zero. ## Utilization targets Both `target_cpu` and `target_memory` are percentages of each pod's **request** - the minimum CPU and memory you set for the service - not its limit, and not the capacity of the underlying node. ```json ops.json theme={null} { "autoscaling": { "max_replicas": 12, "target_cpu": 70 } } ``` Allowed range is `1` to `500`. Values above 100 are legal and sometimes what you want: `"target_cpu": 150` means "run each pod at 1.5x the CPU it requested before adding another". A target below 1 is ignored, as it would pin the service at `max_replicas` permanently. You can set both targets. LocalOps then scales on whichever one asks for more replicas, so neither resource gets starved. > [!WARNING] > > Prefer `target_cpu` where it works. Most runtimes - the JVM, Node, Go - never return freed heap to the operating > system, so memory utilization only ratchets upwards. A service scaling on `target_memory` may scale out under load and > never scale back in. LocalOps logs this warning on every deployment that uses `target_memory`. ## Time-of-day schedules Some load is predictable enough that waiting for a metric to move is too late. `schedules` holds your service at a floor for a window, so capacity is already there when traffic arrives: ```json ops.json theme={null} { "autoscaling": { "max_replicas": 20, "target_cpu": 70, "schedules": [ { "days": ["monday", "tuesday", "wednesday", "thursday", "friday"], "start_time": "09:00", "end_time": "18:00", "timezone": "Asia/Kolkata", "replicas": 8 }, { "days": ["saturday"], "start_time": "00:00", "end_time": "23:00", "timezone": "UTC", "replicas": 3 } ] } } ``` ### Schedule arguments | Key | Required | Description | | - | - | - | | `days` | Yes | Days the window opens on, as lowercase day names: `sunday` through `saturday`. Each day may appear once. | | `start_time` | Yes | When the window opens, as a 24-hour zero-padded `HH:mm` time, such as `09:00`. | | `end_time` | Yes | When the window closes, in the same format. Must differ from `start_time`. | | `timezone` | Yes | IANA timezone name, such as `Asia/Kolkata` or `America/New_York`. Both times are read in this zone. | | `replicas` | Yes | The floor to hold for the duration of the window. | Schedules are deliberately not raw cron expressions. One `days` list drives both the start and the end of a window, so a window can't open on weekdays and close every day by mistake. ### Overnight windows If `end_time` is at or before `start_time`, the window runs overnight and closes on the following day. For example, `"days": ["friday"]` with `"start_time": "22:00"` and `"end_time": "06:00"` holds the floor from Friday 22:00 until Saturday 06:00. LocalOps handles the day shift for you. `timezone` has no default on purpose. A business-hours window without one would silently mean UTC, which is almost never what was intended. A schedule sets a floor, not a fixed count. Your utilization targets keep working inside the window and can take the service above the scheduled number, up to `max_replicas`. You can declare up to 12 windows per service. Beyond that, only the first 12 are kept. A window asking for more replicas than `max_replicas` is capped at the ceiling, and one asking for fewer than the service's container count is raised to that count. ## Proactive and reactive scaling The two kinds of trigger behave differently, and most services want both. `schedules` are **proactive**. The window opens on a clock, so capacity is in place before the traffic it was meant for arrives. Use them for load you can predict - business hours, a nightly batch, a weekly report run. `target_cpu` and `target_memory` are **reactive**. Nothing moves until utilization has already risen, so there is always a short lag between load arriving and replicas appearing. Use them for load you can't predict, and as the safety net above whatever your schedules reserved. A common shape is a schedule that covers the working day and a CPU target that handles the spikes within it. ## Where the new pods run Adding replicas only helps if there is somewhere to put them. Every service runs on a node group you assign it to, and each node group has a minimum and maximum number of nodes. When your new replicas don't fit on the nodes already running, the node group expands to make room, up to the maximum you set: * **On AWS**, the EKS managed node group backing your service adds EC2 instances of its configured instance type and capacity type (on-demand or spot), within its min and max size. An AWS node group holds between 2 and 20 nodes. * **On GCP**, the GKE node pool backing your service adds nodes of its configured machine type, within its minimum and maximum node count. When load falls and replicas are removed, nodes that are no longer needed are released the same way, back down to the minimum. > [!WARNING] > > Set the maximum node count before you rely on autoscaling. Visit the **Node Groups** section in your environment and > set minimum and maximum values on the node group your service is assigned to. If the maximum is too low to fit the > replicas `max_replicas` allows, the extra pods have nowhere to be scheduled and stay pending - your service stops > scaling at whatever the nodes can hold, not at the ceiling you declared in `ops.json`. A service runs only on the node group it is assigned to. It can't spill over onto another node group's spare capacity, so it is the max of *that* node group that bounds how far your service can scale. If you run several autoscaling services on one node group, size it for all of them peaking together. > [!NOTE] > > New nodes take roughly 2 to 3 minutes to be provisioned, join the cluster and start running pods. This applies only > when new nodes are actually required. If the nodes already running have room to spare, your new replicas start > immediately and there is no wait at all - which is another reason to give schedules a little lead time on the traffic > you expect. ## Setting it from the console instead The same configuration can be set through the LocalOps console rather than committed to your repo. Both are equal sources, and `ops.json` wins when both exist. Precedence is all-or-nothing: an `autoscaling` block in `ops.json` replaces the stored configuration outright rather than merging with it field by field. This keeps things predictable - your service can never end up half governed by `ops.json` and half by a console someone else edited. > [!WARNING] > > Because it replaces rather than merges, an `ops.json` declaring only `target_cpu` discards schedules that were set > through the console. If you move autoscaling into `ops.json`, move all of it. If your `ops.json` block can't be used - a missing `max_replicas`, say - LocalOps falls back to the configuration stored through the console rather than leaving the service unscaled, and says so in the deployment logs. A malformed push never silently strips a service of autoscaling it already had. ## When a service can't autoscale Some services are refused outright, whichever way the configuration was set. The deployment continues, and the reason is logged. * **Preview services never autoscale.** A preview's `ops.json` comes off a pull request branch, so any PR author could otherwise raise your bill, and one stored ceiling would multiply across every open PR. Previews exist to validate a change, not to serve load. See [ephemeral environments](/environment/services/ops-json#ephemeral-databases-and-services-for-pull-request-previews). * **Helm chart services** are scaled by their own chart values at install time. `autoscaling` isn't an accepted key in a helm service's `ops.json` at all. * **Only web, worker and internal services** can autoscale. Cron and job services aren't long-running workloads, so there is nothing to scale on load. * **Services with a `disk` volume** can't autoscale. Durable storage means each replica owns its own volume, so replicas can't be added on demand. Scratch space (`mem`) and mounted secrets are fine. See [volumes](/environment/services/ops-json#volumes). ## Nothing here fails a deployment Like [`deploy_timeout`](/environment/services/ops-json#deploy-timeout), a value outside the allowed range is corrected rather than treated as a broken deployment. Every correction is logged. | Declared | What happens | | - | - | | `max_replicas` above `50` | Capped at `50` | | `max_replicas` below the service's container count | Raised to match the container count | | `target_cpu` or `target_memory` below `1` | That trigger is ignored | | `target_cpu` or `target_memory` above `500` | Capped at `500` | | More than 12 schedules | Only the first 12 are kept | | A schedule's `replicas` above `max_replicas` | Capped at `max_replicas` | | A schedule's `replicas` below the container count | Raised to the container count | | A schedule with missing or invalid `days`, times, timezone or `replicas` | That window is dropped, the others still apply | | Service stopped (container count `0`) | Autoscaling paused, resumes when the count is raised | A block that couldn't work at all - no `max_replicas`, no trigger, or a utilization target with no matching resource request - is ignored entirely, with the reason in your deployment logs. ## Verify it worked Check your deployment logs. Every value that was clamped, every schedule dropped, every fallback to the console configuration and every reason a block was refused is written there, naming which source it came from. Deployment logs are where you confirm the numbers you declared are the numbers in force. You can also see the replicas actually running for a service in the LocalOps console, shown as `(x/y)` - x running out of y total. # Aurora (Postgres & MySQL) Source: https://docs.localops.co/environment/services/aws/aurora Provision Amazon Aurora clusters - MySQL/Postgres Your service(s) may want a database that scales its capacity on its own, or that offers a separate endpoint for read-only traffic. This guide will show you steps to create and access Amazon Aurora clusters that offer fully managed Postgres/MySQL compatible databases. Aurora separates storage from compute. One cluster owns a single storage volume that grows on its own, and one or more compute instances attach to it - a **writer** that handles all writes, plus optional **readers** that serve read-only traffic from the same volume. Since readers share the writer's storage, adding one gives you read capacity immediately, with no data copy to manage. > [!TIP] > > Use the [`rds`](/environment/services/aws/rds) dependency for a single, straightforward database instance. Choose > `aurora` when you want a separate read endpoint, faster failover, or capacity that scales itself. ## Declarative & Automatic using `ops.json`: For your service, if you need one or more Aurora clusters, you can add `ops.json` in the root directory of Github repo you've connected for the service. > [!TIP] > > Learn more about configuring dependencies using `ops.json`[here](/environment/services/ops-json). And add Aurora clusters as a dependency, like below. ```json theme={null} { "dependencies": { "aurora": { "clusters": [ { "id": "orders", "prefix": "orders", "engine": "aurora-postgres", "version": "16.4", "db_name": "orders", "serverless": { "min_acu": 0.5, "max_acu": 16 }, "replicas": 1, "maintenance_window": "sun:05:00-sun:06:00", "cluster_parameters": [ { "name": "rds.force_ssl", "value": "1", "apply_method": "pending-reboot" } ], "parameters": [ { "name": "max_connections", "value": "2000", "apply_method": "pending-reboot" } ], "exports": { "DATABASE_URL": "$dsn", "DATABASE_RO_URL": "$readerDsn", "DB_HOST": "$address", "DB_PORT": "$port", "DB_NAME": "$dbName", "DB_USER": "$username", "DB_PASSWORD": "$password" } } ] } } } ``` You can add as many Aurora clusters as you want. Arguments you can add in each cluster object above: 1. `id` - Alphanumeric string. Must be unique amongst the clusters you've declared above. Changing this string will replace the original cluster with new one. 2. `prefix` - Alphanumeric string. Will be used as a prefix in the name of your cluster, to make it recognizable in the AWS console. 3. `engine` - Provide either `aurora-postgres` or `aurora-mysql`. Required. 4. `version` - Pick a version for your cluster - `16.4` style for Postgres, `8.0.mysql_aurora.3.06.0` style for MySQL. Ensure Aurora supports it, by referring to AWS docs - [Postgres](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraPostgreSQL.Updates.html) / [MySQL](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/AuroraMySQL.Updates.html). Default: `""` - so it will provision the latest version as decided by AWS. Required when you set `parameters` or `cluster_parameters`. 5. `db_name` - Name of the initial database created in the cluster. Default: `db` + `id`. 6. `serverless` - Object with `min_acu` and `max_acu`, to run the cluster on **Aurora Serverless v2**. Capacity scales in place between the floor and ceiling you set, in Aurora Capacity Units (ACUs) - one ACU is roughly 2 GiB of memory with proportional CPU. Scaling happens in seconds without a failover or a dropped connection, so this suits traffic that varies through the day. `min_acu` is what you pay for around the clock, so keep it at the smallest value your idle workload tolerates (`0.5` is the floor); `max_acu` is only billed when Aurora actually scales up. Default: `0.5`-`4` ACU. Mutually exclusive with `instance_type`. 7. `instance_type` - Aurora instance class, e.g., `db.r6g.large`, to run the cluster on **provisioned** instances instead. Every instance in the cluster runs at that size continuously, so cost is predictable and there is no scaling latency - suited for a production database under steady load. All Aurora instance classes are prefixed with `db.` - memory-optimized (`db.r6g`, `db.r7g`) or burstable (`db.t4g`). Refer to [AWS docs](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/Concepts.DBInstanceClass.html) for available sizes. Mutually exclusive with `serverless` - declaring both is an error. 8. `replicas` - Number of read replicas provisioned in addition to the writer. Valid values are `0` to `14` (Aurora supports at most 15 instances in a cluster). Default: `0`. 9. `maintenance_window` - The window to perform maintenance in, in UTC. Syntax: "ddd:hh24:mi-ddd:hh24:mi". Eg: "sun:05:00-sun:06:00". Minimum 30 minutes. Default: assigned by AWS. 10. `cluster_parameters` - Optional list of DB **cluster** parameter group settings, applied to the whole cluster - every instance shares them. This is where connection and replication settings live: `rds.force_ssl`, `require_secure_transport`, `shared_preload_libraries`. 11. `parameters` - Optional list of DB parameter group settings, applied **per instance**: `max_connections`, `work_mem`, `statement_timeout`. Each entry in `cluster_parameters` and `parameters` is an object with the following keys: * `name` - Name of the parameter. Must be a valid parameter for the chosen `engine` and `version`. If you are unsure which of the two lists it belongs to, check whether the AWS docs list it under *DB cluster parameter group* or *DB parameter group* - putting one in the wrong place is rejected by AWS. * `value` - Value to set for the parameter. Always specified as a string. * `apply_method` - When the change should take effect. Required. One of `immediate` or `pending-reboot`. Static parameters only accept `pending-reboot`. Setting either list requires an explicit `version`, since the engine version determines which parameters exist. 12. `skip_preview` - Set to `true` to not create this cluster for ephemeral preview services. Default: `false`. 13. `preview_only` - Set to `true` to create this cluster *only* for ephemeral preview services. Default: `false`. 14. `exports` - Set of key value pairs. Keys are the ENVIRONMENT VARS we will pass to your code / containers. Values are the properties of the Aurora cluster provisioned. See below for available properties. > [!WARNING] > > Changing `id`, `db_name` or switching `engine` between Postgres and MySQL will delete & replace the original Aurora > cluster with a new, empty one - the database name and master username are derived from `id`. Treat `id` as permanent > once the cluster holds data you care about. Switching between Serverless v2 and provisioned is *not* destructive - the > instances are resized and the data stays put. Available properties of the Aurora cluster to use in `exports`: 1. `$name` - Name of the Aurora cluster. 2. `$arn` - Amazon resource name of the cluster. Eg., `arn:aws:rds:..` 3. `$endpoint` - The writer connection endpoint in `address:port` format. 4. `$address` - DNS address of the writer endpoint. 5. `$readerEndpoint` - The reader connection endpoint in `address:port` format. 6. `$readerAddress` - DNS address of the reader endpoint. 7. `$port` - The port your code will use to access the cluster - `5432` for Postgres, `3306` for MySQL. 8. `$dbName` - Name of the database created under the cluster. 9. `$username` - Username of the master database user. 10. `$passwordArn` - Password of the user `$username` is automatically generated, encrypted and maintained by Aurora in AWS Secrets Manager. Your code can read the password from Secrets Manager using this `$passwordArn`. 11. `$password` - The plaintext password of the user `$username`. LocalOps resolves the password from AWS Secrets Manager and injects it directly as an environment variable, so your code can use it without calling the Secrets Manager API. Treat this value as a secret. 12. `$dsn` - Ready-to-use connection string for the **writer**, in the standard URL form for the chosen engine (e.g., `postgres://$username:$password@$address:5432/$dbName`). Treat this value as a secret since it embeds the password. 13. `$readerDsn` - Same, for the **reader** endpoint. Placeholder names are case-sensitive, and an unrecognized one fails the deployment with a message naming the offending variable - so a typo surfaces immediately instead of becoming an empty environment variable at runtime. ### Reading and writing: A cluster gives you two endpoints, and using both is the main reason to choose Aurora: * **Writer** (`$dsn`, `$endpoint`, `$address`) - send all writes here. It always points at the current writer and follows automatically if Aurora promotes a replica during failover, so your code doesn't have to reconnect to a new address. * **Reader** (`$readerDsn`, `$readerEndpoint`, `$readerAddress`) - distributes connections across your read replicas. Point reports, analytics, search and any read-heavy background job here to keep that load off the writer. With `replicas: 0` the reader endpoint resolves to the writer, so it is safe to wire both into your app from day one and add replicas later without a code change. > [!NOTE] > > Replicas are typically milliseconds behind the writer, but not zero. If a request writes a row and then immediately > reads it back, read that one through the writer (`$dsn`). ### Lifecycle: If you have provided `ops.json` at the root of the git repository, it will be processed if a corresponding service in any of your active environment points at the same repository as source and when a deployment is triggered. * When the service is spinned up first time or when a new deployment is triggered, `ops.json` is parsed for processing. Resources declared in the `dependencies` object will be provisioned before your code starts to run. * Resources with same `id` are provisioned only once for the life of the service. And updated when there is a change in one of the properties above. ACU range, replica count, instance type, parameters and maintenance window are all applied in place. * Keys in `exports` object will be passed as enviroment variables to your service. * When the service is deleted, the provisioned Aurora clusters are deleted from the cloud account immediately & automatically, after taking a final snapshot. * A first deployment takes several minutes - Aurora provisions the cluster before the instances, and the writer must be available before your containers start. Each service that declares an `aurora` dependency gets its own cluster. To have several services share one database, declare it in the `ops.json` of a single service and pass the connection details to the other services as [secrets](/environment/services/secrets). ### Private only access: Aurora clusters can be accessed from your code just as usual using your SQL-compatible DB libraries or ORMs. All Aurora clusters are created only in the private subnets of the same VPC where your environment is running. And they are attached with following security group. Ingress: 1. From source: `10.0.0.0/16` (Your environment's VPC CIDR IP range) 2. At port: `5432` (for Postgres) or `3306` (for MySQL) 3. Protocol: `TCP` So only workload/containers/servers from within your environment's VPC can access the Aurora cluster. There is no way to make the cluster publicly reachable through `ops.json`. This means you cannot point `psql` or a desktop SQL client at the database directly from your laptop. To get an interactive SQL shell, or to reach the database from a GUI client, connect from inside the cluster using the LocalOps CLI - see [Connect to your database](/cli/usage#connect-to-your-databases-or-cache). ### Reading Database password: AWS generates the master password, stores it in your AWS account's Secrets Manager and rotates it automatically. LocalOps grants your service permission to read that secret, so `$password` and `$dsn` always reflect the current value as of your last deployment. Since the password is rotated periodically, the `$password` and `$dsn` values injected at container start can go stale between rotations. Also export `$passwordArn` and have your code fall back to reading the current password from AWS Secrets Manager using that ARN whenever a DB connection fails with a bad-password / auth error, then retry the connection with the freshly fetched password. ### Pre-configured for production use: All Aurora clusters are pre-configured for production use. 1. Daily backup is enabled. With 30-day retention for each backup. 2. Encryption is enabled to safeguard data at rest. 3. Enhanced monitoring is enabled at 60-second resolution. 4. A final snapshot is created automatically when the cluster is about to get deleted. 5. Changes are deferred to the maintenance window, so a deployment doesn't cause an unplanned restart. ### Ephemeral preview environments: For speed and cost savings, preview services created for [pull request previews](https://localops.co/blog/introducing-pull-request-previews) get a deliberately smaller, cheaper cluster: 1. The writer only - `replicas` is ignored. 2. Encryption at rest and the final snapshot on teardown are turned off. 3. Backup retention is one day, the minimum Aurora allows. 4. Changes are applied immediately rather than deferred to the maintenance window. Every preview service still gets its **own cluster**, and a Serverless v2 cluster bills continuously even at `0.5` ACU for as long as the preview exists. If that isn't worth it, set `skip_preview: true` and point previews at a shared database using a regular [environment variable](/environment/services/secrets). # Elasticache Redis, Valkey & Memcache Source: https://docs.localops.co/environment/services/aws/elasti-cache Provision AWS Elastic Cache clusters - Redis/Valkey/Memcache Your service(s) may want to store/access data in a Redis/Valkey/Memcache instance. This guide will show you steps to create and access Amazon ElastiCache cluster that offers fully managed Redis/Valkey/Memcache databases. ## Declarative & Automatic using `ops.json`: For your service, if you need one or more ElastiCache clusters, you can add `ops.json` in the root directory of Github repo. > [!TIP] > > Learn more about configuring dependencies using `ops.json`[here](/environment/services/ops-json). And add ElastiCache clusters as a dependency, like below. ```json theme={null} { "dependencies": { "elasticache": { "clusters": [ { "id": "test123", "prefix": "testdep123", "engine": "redis", "version": "7.0", "instance_type": "cache.t4g.small", "num_nodes": 1, "parameters": [ { "name": "maxmemory-policy", "value": "volatile-lru" } ], "exports": { "MY_ELASTICACHE_CLUSTER_NAME": "$name", "MY_ELASTICACHE_CLUSTER_ARN": "$arn", "MY_ELASTICACHE_CLUSTER_ENDPOINT": "$endpoint", "MY_ELASTICACHE_CLUSTER_ADDRESS": "$address", "MY_ELASTICACHE_CLUSTER_PORT": "$port" } } ] } } } ``` You can add as many clusters as you want. Arguments you can add in each cluster object above: 1. `id` - Alphanumeric string. Must be unique amongst the instances you've declared above. Changing this string will replace the original cluster with new one. 2. `prefix` - Alphanumeric string. Will be used as a prefix in the name of your cluster. Changing this string will replace the original cluster with new cluster. 3. `engine` - Provide `redis`, `valkey` or `memcache`. Default: \`\`. If you leave this out, we will skip creating the cluster. 4. `version` - Pick a version for your redis, valkey or memcache database. Ensure Elastic Cache supports it, by referring to [AWS docs](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/engine-versions.html). For Valkey, see the [supported Valkey versions](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/supported-engine-versions-valkey.html). 5. `instance_type` - Specify any class of instance in the following groups - "cache.\*". Refer to [AWS docs](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/CacheNodes.SupportedTypes.html) for available sizes. If you leave this out, we will skip creating the cluster. 6. `num_nodes` - The initial number of cache nodes that the cache cluster will have. For Redis, this value must be 1. For Memcached, this value must be between 1 and 40. If this number is reduced on subsequent runs, the highest numbered nodes will be removed. 7. `parameters` - Optional list of cache parameter group settings to apply to the cluster. Each entry is an object with the following keys: * `name` - Name of the parameter (e.g., `maxmemory-policy`). Must be a valid parameter for the chosen `engine` and `version`. Refer to the [Redis/Valkey parameter docs](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/ParameterGroups.Redis.html) or [Memcached parameter docs](https://docs.aws.amazon.com/AmazonElastiCache/latest/mem-ug/ParameterGroups.Memcached.html) for available names. * `value` - Value to set for the parameter. Always specified as a string. When `parameters` is provided, LocalOps creates a dedicated cache parameter group for the cluster and attaches it. Adding, updating or removing entries on subsequent deployments updates the parameter group in-place. 8. `exports` - Set of key value pairs. Keys are the ENVIRONMENT VARS we will pass to your code / containers. Values are the properties of the ElastiCache cluster provisioned. See below for available properties. > [!WARNING] > > Changing `id` or `prefix` string will delete & replace the original ElastiCache cluster with new one. Available properties of the ElastiCache cluster to use in `exports`: 1. `$name` - Name of the ElastiCache cluster 2. `$arn` - Amazon resource name of the ElastiCache cluster 3. `$endpoint` - The connection endpoint in `address:port` format. 4. `$address` - Specifies the DNS address of the ElastiCache master node. 5. `$port` - Specifies the port you will use to access the cluster node. Export `$endpoint`, or `$address` and `$port`, and you can open `redis-cli` against the cluster or reach it from a local GUI client with the LocalOps CLI - see [Connect to your databases or cache](/cli/usage#connect-to-your-databases-or-cache). ### Lifecycle: If you have provided `ops.json` at the root of the git repository, it will be processed if a corresponding service in any of your active environment points at the same repository as source and when a deployment is triggered. * When the service is spinned up first time or when a new deployment is triggered, `ops.json` is parsed for processing. Resources declared in the `dependencies` object will be provisioned before your code starts to run. * Resources with same `id` are provisioned only once for the life of the service. And updated when there is a change in one of the properties above. * Keys in `exports` object will be passed as enviroment variables to your service. * When the service is deleted, the provisioned elastic cache clusters are deleted from the cloud account immediately & automatically. ### Private only access: Elastic cache clusters can be accessed from your code just as usual using $endpoint or $address above, and your DB libraries. All Elastic cache clusters are created only in the private subnets of the same VPC where your environment is running. And they are attached with following security group. Ingress: 1. From source: `10.0.0.0/16` (Your environment's VPC CIDR IP range) 2. At port: `6379` (for Redis) or `11211` (for Memcache) 3. Protocol: `TCP` So only workload/containers/servers from within your environment's VPC can access the Elastic cache cluster ### Pre-configured for production use: All elastic cache clusters are pre-configured for production use. 1. Daily backup is enabled. With 30-day retention for each backup. 2. Encryption is enabled to safeguard data at rest. 3. Backup is created automatically when the cluster is about to get deleted. For speed and cost savings reasons, all the above are turned off in ephemeral services we create in the case of [pull request previews](https://localops.co/blog/introducing-pull-request-previews). ## Manual provisioning of new Elastic-cache cluster: To proceed with this guide, you would need access to: 1. AWS console with permissions to create RDS database 2. LocalOps console Goal is to create a Elasticache instance (Redis, for this guide) in AWS and give your environment/service(s) access to it. Please follow the steps below to proceed: ### 1. Fetch the VPC and private subnet IDs To give your environment and service(s) access to a Elasticache instance, you need to create the elasticache instance within the **same VPC and region** used by the environment. Navigate to LocalOps console and the environment you created. In the environment's overview section, 1. Pick/copy the VPC ID and Private Subnet IDs 2. Note down the region You will use these in the next step while creating the Elasticache instance. ### 2. Create Elasticache instance Login to the same AWS account and region where you created the environment using LocalOps. And create new Elasticache database with appropriate engine - Postgres/MySQL. You may have to create a subnet group first before creating the Elasticache instance. While creating the subnet group, use the same VPC ID and private subnet IDs you copied above. > [!TIP] > > For the same app, if you already have a Elasticache instance in a same or different AWS account, VPC or region, you > can very well use the same and skip creating a new Elasticache instance. We can connect your environment/services and > the database via *VPC peering*. Learn more about using an existing database below. You can follow this [official AWS guide](https://docs.aws.amazon.com/AmazonElastiCache/latest/dg/GettingStarted.serverless-redis.step1.html) to create your Redis cache. Elasticache offers two deployment modes - *ElastiCache Serverless* & *Self-designed ElastiCache clusters*. Steps to connect either of them to your environments managed by LocalOps, are same. Record the database endpoint, username and password. ### 3. Add instance endpoint and credentials as secrets Last step is to give your service(s) access to the RDS database. In LocalOps console, navigate the Service settings within the corresponding environment. In secrets section, add a new key value pair like ``` - Key: `REDIS_HOST` - Value: `your-instance-endpoint` - Key: `REDIS_USERNAME` - Value: `your-instance-username` - Key: `REDIS_PASS` - Value: `your-instance-password` ``` Learn more about secrets [here](/environment/services/secrets). You can name the key in any way you want. In your code, you can access `REDIS_*` environment variables to connect and access the database. Repeat the above process for each Elasticache instance you want to create for each environment - test, staging, production, etc., That's it! ## Use pre-existing Elasticache instance ### 1. Setup VPC peering Your LocalOps environment is created in its own VPC in the chosen AWS account and region. For the same application, if you already have a Elasticache instance running in the same/different AWS account, you can connect/access it with the corresponding LocalOps environment using Amazon VPC peering. VPC peering lets you connect two VPCs from same or different AWS account/region so that resources in one VPC can access the resources in another VPC like they belong to the same network. Ping us on slack / write to us at [support@localops.co](mailto:support@localops.co) / [book a call](https://go.localops.co/meet-engineer) with our team to guide you on this. ### 2. Add instance endpoint and credentials as secrets Last step is to give your service(s) access to the RDS database. In LocalOps console, navigate the Service settings within the corresponding environment. In secrets section, add a new key value pair like ``` - Key: `REDIS_HOST` - Value: `your-instance-endpoint` - Key: `REDIS_USERNAME` - Value: `your-instance-username` - Key: `REDIS_PASS` - Value: `your-instance-password` ``` Learn more about secrets [here](/environment/services/secrets). You can name the key in any way you want. In your code, you can access `REDIS_*` environment variables to connect and access the database. That's it. 🎉 # MSK (Kafka) Source: https://docs.localops.co/environment/services/aws/msk Provision Amazon MSK Kafka clusters - provisioned or serverless Your service(s) may want to publish and consume events through Apache Kafka. This guide will show you how to create and access Amazon MSK (Managed Streaming for Apache Kafka) clusters, either **provisioned** clusters with brokers you size yourself, or **serverless** clusters that scale on their own. ## Declarative & Automatic using `ops.json`: For your service, if you need one or more MSK clusters, you can add `ops.json` in the root directory of Github repo. > [!TIP] > > Learn more about configuring dependencies using `ops.json`[here](/environment/services/ops-json). And add MSK clusters as a dependency, like below. ### Provisioned cluster ```json theme={null} { "dependencies": { "msk": { "clusters": [ { "id": "events", "type": "provisioned", "version": "3.9.x", "instance_type": "kafka.t3.small", "broker_count": 2, "storage_gb": 20, "parameters": [{ "name": "auto.create.topics.enable", "value": "false" }], "exports": { "KAFKA_NAME": "$name", "KAFKA_ARN": "$arn", "KAFKA_BROKERS": "$bootstrapBrokers", "KAFKA_PORT": "$port", "KAFKA_REGION": "$region", "KAFKA_SASL_MECHANISM": "$saslMechanism", "KAFKA_SECURITY_PROTOCOL": "$securityProtocol", "KAFKA_USERNAME": "$username", "KAFKA_PASSWORD": "$password", "KAFKA_PASSWORD_ARN": "$passwordArn" } } ] } } } ``` ### Serverless cluster ```json theme={null} { "dependencies": { "msk": { "clusters": [ { "id": "events", "type": "serverless", "exports": { "KAFKA_NAME": "$name", "KAFKA_ARN": "$arn", "KAFKA_BROKERS": "$bootstrapBrokers", "KAFKA_PORT": "$port", "KAFKA_REGION": "$region", "KAFKA_SASL_MECHANISM": "$saslMechanism", "KAFKA_SECURITY_PROTOCOL": "$securityProtocol" } } ] } } } ``` You can add as many clusters as you want. Arguments you can add in each cluster object above: 1. `id` - Alphanumeric string. Must be unique amongst the clusters you've declared above. Changing this string will replace the original cluster with new one. 2. `type` - `provisioned` or `serverless`. Default: `provisioned`. 3. `version` - Provisioned only, required. A Kafka version MSK supports for new clusters, eg., `3.8.x` or `3.9.x`. Recent MSK versions use the `x` form - write it exactly like that. Run `aws kafka list-kafka-versions` or refer to [AWS docs](https://docs.aws.amazon.com/msk/latest/developerguide/supported-kafka-versions.html) for the list. Older versions may be rejected for new clusters, eg., MSK no longer accepts `3.6.0` for standard brokers such as `kafka.t3.small`. 4. `instance_type` - Provisioned only. Broker instance type, must start with `kafka.`, eg., `kafka.t3.small`, `kafka.m5.large`. Refer to [AWS docs](https://docs.aws.amazon.com/msk/latest/developerguide/broker-instance-sizes.html) for available sizes. Default: `kafka.t3.small`. 5. `broker_count` - Provisioned only. Total number of brokers. Brokers are spread evenly over 2 or 3 availability zones, so this must be 2 or more and a multiple of 2 or 3 (2, 3, 4, 6, 8, 9, ...). Default: `2`. Once the cluster exists, its brokers stay in the same availability zones: a new `broker_count` must still spread evenly over them, or the deployment fails with an error. 6. `storage_gb` - Provisioned only. EBS storage per broker, in GB. Between `1` and `16384`. Default: `20`. MSK can only increase storage on an existing cluster, never reduce it. 7. `parameters` - Provisioned only. Optional list of Kafka broker settings (`server.properties`). Each entry is an object with the following keys: * `name` - Name of the setting (eg., `auto.create.topics.enable`). Refer to [AWS docs](https://docs.aws.amazon.com/msk/latest/developerguide/msk-configuration-properties.html) for the settings MSK allows. * `value` - Value to set. Always specified as a string. When `parameters` is provided, LocalOps creates an MSK configuration for the cluster and attaches it. 8. `skip_preview` - Set to `true` to not create this cluster for ephemeral preview services. Default: `false`. 9. `preview_only` - Set to `true` to create this cluster *only* for ephemeral preview services. Default: `false`. 10. `exports` - Set of key value pairs. Keys are the ENVIRONMENT VARS we will pass to your code / containers. Values are the properties of the MSK cluster provisioned. See below for available properties. Serverless clusters have no brokers to size: setting `version`, `instance_type`, `broker_count`, `storage_gb` or `parameters` on a `serverless` cluster fails the deployment with an error, instead of being ignored. > [!WARNING] > > Changing `id` will delete & replace the original MSK cluster with a new, empty one. `type` cannot be changed on an > existing cluster at all - the deployment fails with an error, since switching would replace the cluster and lose its > data. To move between provisioned and serverless, declare a new cluster with a new `id`. Available properties of the MSK cluster to use in `exports`: 1. `$name` - Name of the MSK cluster 2. `$arn` - Amazon resource name of the MSK cluster 3. `$bootstrapBrokers` - Comma separated list of bootstrap brokers in `host:port` format. Pass this to your Kafka client as its brokers list. 4. `$port` - Port the brokers listen on: `9096` for provisioned, `9098` for serverless. 5. `$region` - AWS region of the cluster 6. `$saslMechanism` - `SCRAM-SHA-512` for provisioned, `OAUTHBEARER` for serverless. 7. `$securityProtocol` - Always `SASL_SSL`. 8. `$username` - Provisioned only. SASL/SCRAM username, derived from `id`. 9. `$password` - Provisioned only. SASL/SCRAM password. 10. `$passwordArn` - Provisioned only. ARN of the AWS Secrets Manager secret holding the username and password. > [!WARNING] > > Serverless clusters have no username or password. Exporting `$username`, `$password` or `$passwordArn` from a > `serverless` cluster fails the deployment with an error - remove those exports. ### Lifecycle: If you have provided `ops.json` at the root of the git repository, it will be processed if a corresponding service in any of your active environment points at the same repository as source and when a deployment is triggered. * When the service is spinned up first time or when a new deployment is triggered, `ops.json` is parsed for processing. Resources declared in the `dependencies` object will be provisioned before your code starts to run. * Resources with same `id` are provisioned only once for the life of the service. And updated when there is a change in one of the properties above, within the limits MSK allows for an existing cluster (see `broker_count` and `storage_gb` above). * Keys in `exports` object will be passed as enviroment variables to your service. * When the service is deleted, the provisioned MSK clusters are deleted from the cloud account. > [!WARNING] > > MSK has no backups or snapshots, so unlike RDS and ElastiCache, no final snapshot is taken before a cluster is > deleted. Deleting the service, changing the cluster's `id` or removing it from `ops.json` deletes the cluster and all > its topic data permanently. If you need the data to outlive the cluster, copy it out continuously, eg., to S3 with > [MSK Connect](https://aws.amazon.com/blogs/big-data/back-up-and-restore-kafka-topic-data-using-amazon-msk-connect/). ### Authentication: Both cluster types accept only authenticated, TLS encrypted connections (`SASL_SSL`). How your code authenticates depends on the `type`. #### Provisioned: username & password (SASL/SCRAM) LocalOps generates a username and password for the cluster, stores them in an AWS Secrets Manager secret encrypted with a dedicated KMS key, and associates the secret with the cluster. Export `$username` and `$password` and pass them to your Kafka client with the `SCRAM-SHA-512` mechanism. #### Serverless: IAM (no keys) Serverless clusters authenticate with IAM only. You don't pass any username, password or AWS secret key - your containers authenticate with the IAM role LocalOps attaches to all the services in your environment. We provision a policy like below on that role for every serverless cluster, covering all topics, consumer groups and transactional ids on that cluster. ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": ["kafka-cluster:Connect", "kafka-cluster:DescribeCluster", "kafka-cluster:WriteDataIdempotently"], "Resource": "your-cluster" }, { "Effect": "Allow", "Action": ["kafka-cluster:*Topic*", "kafka-cluster:ReadData", "kafka-cluster:WriteData"], "Resource": "your-cluster's topics" }, { "Effect": "Allow", "Action": ["kafka-cluster:AlterGroup", "kafka-cluster:DescribeGroup", "kafka-cluster:DeleteGroup"], "Resource": "your-cluster's consumer groups" }, { "Effect": "Allow", "Action": ["kafka-cluster:AlterTransactionalId", "kafka-cluster:DescribeTransactionalId"], "Resource": "your-cluster's transactional ids" }, { "Effect": "Allow", "Action": ["kafka:DescribeClusterV2", "kafka:GetBootstrapBrokers"], "Resource": "your-cluster" } ] } ``` Your Kafka client signs a token with that role and sends it using the `OAUTHBEARER` mechanism. Use AWS's signer library for your language: * Node.js - [`aws-msk-iam-sasl-signer-js`](https://github.com/aws/aws-msk-iam-sasl-signer-js) * Python - [`aws-msk-iam-sasl-signer-python`](https://github.com/aws/aws-msk-iam-sasl-signer-python) * Go - [`aws-msk-iam-sasl-signer-go`](https://github.com/aws/aws-msk-iam-sasl-signer-go) * Java - [`aws-msk-iam-auth`](https://github.com/aws/aws-msk-iam-auth) > [!NOTE] > > Some examples online use the mechanism name `AWS_MSK_IAM`. Only the Java `aws-msk-iam-auth` plugin registers that > name, and other clients don't recognise it. That's why `$saslMechanism` exports `OAUTHBEARER`. Curious to know the IAM role that is used? Visit your environment's main dashboard in LocalOps console to see the role. ### Connecting from your code: Below are Node.js and Java examples, with the exports declared in the `ops.json` examples above. Each works for both cluster types. Topics are not created automatically on serverless clusters, nor on the provisioned example above (`auto.create.topics.enable` is `false`), so each creates the topic first if it's missing. #### Node.js Using [`kafkajs`](https://kafka.js.org): ```js theme={null} const { Kafka } = require('kafkajs'); const { generateAuthToken } = require('aws-msk-iam-sasl-signer-js'); // serverless only const sasl = process.env.KAFKA_SASL_MECHANISM === 'OAUTHBEARER' ? { // Serverless: sign a token with the service's IAM role mechanism: 'oauthbearer', oauthBearerProvider: async () => { const { token } = await generateAuthToken({ region: process.env.KAFKA_REGION }); return { value: token }; }, } : { // Provisioned: username & password mechanism: 'scram-sha-512', username: process.env.KAFKA_USERNAME, password: process.env.KAFKA_PASSWORD, }; const kafka = new Kafka({ clientId: 'my-service', brokers: process.env.KAFKA_BROKERS.split(','), ssl: true, sasl, }); async function main() { const admin = kafka.admin(); await admin.connect(); if (!(await admin.listTopics()).includes('events')) { // -1 uses the cluster's default replication; serverless only accepts that. await admin.createTopics({ topics: [{ topic: 'events', numPartitions: 3, replicationFactor: -1 }], waitForLeaders: true, }); } await admin.disconnect(); const producer = kafka.producer(); await producer.connect(); await producer.send({ topic: 'events', messages: [{ value: 'hello' }] }); await producer.disconnect(); } main(); ``` To consume, use the same `kafka` client with a consumer group: ```js theme={null} async function consume() { const consumer = kafka.consumer({ groupId: 'my-service' }); await consumer.connect(); await consumer.subscribe({ topic: 'events', fromBeginning: true }); await consumer.run({ eachMessage: async ({ partition, message }) => { console.log(`partition ${partition} offset ${message.offset}: ${message.value.toString()}`); }, }); } consume(); ``` #### Java Using the official [`kafka-clients`](https://kafka.apache.org/documentation/#api) library, with AWS's [`aws-msk-iam-auth`](https://github.com/aws/aws-msk-iam-auth) plugin for serverless clusters. Add both to your `pom.xml`: ```xml theme={null} org.apache.kafka kafka-clients 3.9.1 software.amazon.msk aws-msk-iam-auth 2.3.9 ``` ```java theme={null} import java.util.List; import java.util.Optional; import java.util.Properties; import org.apache.kafka.clients.admin.Admin; import org.apache.kafka.clients.admin.NewTopic; import org.apache.kafka.clients.producer.KafkaProducer; import org.apache.kafka.clients.producer.ProducerRecord; import org.apache.kafka.common.serialization.StringSerializer; public class Events { static Properties kafkaProperties() { Properties props = new Properties(); props.put("bootstrap.servers", System.getenv("KAFKA_BROKERS")); props.put("security.protocol", "SASL_SSL"); if ("OAUTHBEARER".equals(System.getenv("KAFKA_SASL_MECHANISM"))) { // Serverless: sign a token with the service's IAM role System.setProperty("aws.region", System.getenv("KAFKA_REGION")); String handler = "software.amazon.msk.auth.iam.IAMOAuthBearerLoginCallbackHandler"; props.put("sasl.mechanism", "OAUTHBEARER"); props.put("sasl.jaas.config", "org.apache.kafka.common.security.oauthbearer.OAuthBearerLoginModule required;"); props.put("sasl.login.callback.handler.class", handler); props.put("sasl.client.callback.handler.class", handler); } else { // Provisioned: username & password props.put("sasl.mechanism", "SCRAM-SHA-512"); props.put("sasl.jaas.config", String.format( "org.apache.kafka.common.security.scram.ScramLoginModule required username=\"%s\" password=\"%s\";", System.getenv("KAFKA_USERNAME"), System.getenv("KAFKA_PASSWORD"))); } return props; } public static void main(String[] args) throws Exception { Properties props = kafkaProperties(); try (Admin admin = Admin.create(props)) { if (!admin.listTopics().names().get().contains("events")) { // Optional.empty() uses the cluster's default replication; serverless only accepts that. admin.createTopics(List.of(new NewTopic("events", Optional.of(3), Optional.empty()))).all().get(); } } props.put("key.serializer", StringSerializer.class.getName()); props.put("value.serializer", StringSerializer.class.getName()); try (KafkaProducer producer = new KafkaProducer<>(props)) { producer.send(new ProducerRecord<>("events", "hello")).get(); } } } ``` To consume, reuse `kafkaProperties()` from above and add a consumer group and deserializers: ```java theme={null} import java.time.Duration; import java.util.List; import java.util.Properties; import org.apache.kafka.clients.consumer.ConsumerRecord; import org.apache.kafka.clients.consumer.KafkaConsumer; import org.apache.kafka.common.serialization.StringDeserializer; public class EventsConsumer { public static void main(String[] args) { Properties props = Events.kafkaProperties(); props.put("group.id", "my-service"); props.put("auto.offset.reset", "earliest"); props.put("key.deserializer", StringDeserializer.class.getName()); props.put("value.deserializer", StringDeserializer.class.getName()); try (KafkaConsumer consumer = new KafkaConsumer<>(props)) { consumer.subscribe(List.of("events")); while (true) { for (ConsumerRecord record : consumer.poll(Duration.ofSeconds(1))) { System.out.printf("partition %d offset %d: %s%n", record.partition(), record.offset(), record.value()); } } } } } ``` ### Connecting from your terminal: To list topics, publish test messages or watch a topic by hand, run `ops connect --dep` from the [LocalOps CLI](/cli/usage#open-a-kafka-shell). It opens a shell inside your environment with Kafka's command-line scripts already set up for the cluster, provisioned or serverless. ```sh theme={null} ops connect --env staging --svc api --dep events ``` It needs `$bootstrapBrokers` in the cluster's `exports`. ### Private only access: All MSK clusters are created only in the private subnets of the same VPC where your environment is running. And they are attached with following security group. Ingress: 1. From source: Your environment's VPC CIDR IP range 2. At port: `9096` (provisioned) or `9098` (serverless) 3. Protocol: `TCP` So only workload/containers/servers from within your environment's VPC can access the MSK cluster. Provisioned brokers are spread over 2 or 3 of your environment's private subnets, depending on `broker_count`. Serverless clusters need private subnets in at least 2 availability zones. ### Encryption: 1. Traffic between your code and the brokers, and between brokers, is encrypted with TLS. 2. MSK encrypts data at rest by default. ### Ephemeral preview environments: Every preview service created for [pull request previews](/use-cases/ephemeral) gets its **own cluster**, which bills for as long as the preview exists. If that isn't worth it, set `skip_preview: true` and point previews at a shared cluster using regular [environment variables](/environment/services/secrets). # OpenSearch Source: https://docs.localops.co/environment/services/aws/opensearch Provision Amazon OpenSearch domains for search and analytics Your service(s) may want to index, search and analyze data using OpenSearch. This guide will show you steps to create and access Amazon OpenSearch domains that offer fully managed OpenSearch clusters. ## Declarative & Automatic using `ops.json`: For your service, if you need one or more OpenSearch domains, you can add `ops.json` in the root directory of Github repo you've connected for the service. > [!TIP] > > Learn more about configuring dependencies using `ops.json`[here](/environment/services/ops-json). And add OpenSearch domains as a dependency, like below. ```json theme={null} { "dependencies": { "opensearch": { "domains": [ { "id": "productsearch", "prefix": "product-search", "engine_version": "OpenSearch_2.11", "instance_type": "t3.small.search", "node_count": 3, "ebs_volume_size": 20, "ebs_volume_type": "gp3", "dedicated_master": false, "publicly_accessible": false, "advanced_options": [], "exports": { "PRODUCT_SEARCH_NAME": "$name", "PRODUCT_SEARCH_ARN": "$arn", "PRODUCT_SEARCH_ENDPOINT": "$endpoint", "PRODUCT_SEARCH_ADDRESS": "$address", "PRODUCT_SEARCH_PORT": "$port", "PRODUCT_SEARCH_USERNAME": "$username", "PRODUCT_SEARCH_PASSWORD_ARN": "$passwordArn", "PRODUCT_SEARCH_PASSWORD": "$password", "PRODUCT_SEARCH_DSN": "$dsn" } } ] } } } ``` You can add as many OpenSearch domains as you want. Arguments you can add in each domain object above: 1. `id` - Alphanumeric string. Must be unique amongst the domains you've declared above. Changing this string will replace the original domain with new one. 2. `prefix` - Alphanumeric string. Will be used as a prefix in the name of your domain. Changing this string will replace the original domain with new domain. 3. `engine_version` - The OpenSearch (or legacy Elasticsearch) engine version to provision. Format is `OpenSearch_X.Y` (e.g., `OpenSearch_2.11`) or `Elasticsearch_X.Y`. Refer to the [supported versions](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/what-is.html#choosing-version). 4. `instance_type` - Data node instance type. Must end with `.search` - e.g., `t3.small.search`, `m6g.large.search`. Refer to [AWS docs](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/supported-instance-types.html) for available sizes. Default: `t3.small.search`. 5. `node_count` - Number of data nodes in the cluster. Default: `3` in production, forced to `1` in ephemeral preview environments. Valid values are `1`, or any number that divides evenly across 2 or 3 Availability Zones (`1`, `2`, `3`, `4`, `6`, `8`, `9`, ...) — LocalOps picks the AZ count for you and rejects values that don't fit. `node_count=2` in production is also rejected unless `dedicated_master` is `true`, because a 2-node quorum loses majority on any single node failure. 6. `ebs_volume_size` - Size of the EBS volume attached to each data node, in GB. Default: `20`. 7. `ebs_volume_type` - Type of EBS volume to attach to each data node. One of `gp3`, `gp2`, `io1`, `standard`. Refer to [AWS docs](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/createdomain-configure-storage.html) for guidance. Default: `gp3`. 8. `dedicated_master` - Set to `true` to provision dedicated master nodes separate from data nodes. When enabled, LocalOps provisions `3` dedicated masters (the AWS-recommended count for production). Recommended for clusters with more than a few data nodes, or to safely run a 2-node data tier. Ignored in ephemeral preview environments. Default: `false`. 9. `dedicated_master_type` - Instance type for the dedicated master nodes when `dedicated_master` is `true`. Must end with `.search`. Default: same as `instance_type`. 10. `publicly_accessible` - Set it to `true` if you need this domain to be reachable publicly on the internet. You would want this to be `false` most of the time. When `false`, the domain is attached to your environment's VPC and private subnets; when `true`, the domain is exposed over the public internet and access is gated by HTTPS + the fine-grained access control master user. Default: `false`. 11. `advanced_options` - Optional list of advanced cluster-level options to set on the OpenSearch domain. Each entry is an object with the following keys: * `name` - Name of the advanced option (e.g., `rest.action.multi.allow_explicit_index`, `override_main_response_version`). Refer to the [AWS advanced options docs](https://docs.aws.amazon.com/opensearch-service/latest/developerguide/createupdatedomains.html#createdomain-configure-advanced-options) for available names. * `value` - Value to set for the option. Always specified as a string. Pass an empty list `[]` if you don't need to set any advanced options. 12. `exports` - Set of key value pairs. Keys are the ENVIRONMENT VARS we will pass to your code / containers. Values are the properties of the OpenSearch domain provisioned. See below for available properties. > [!WARNING] > > Changing `id` or `prefix` string will delete & replace the original OpenSearch domain with new one. Available properties of the OpenSearch domain to use in `exports`: 1. `$name` - Name of the OpenSearch domain. 2. `$arn` - Amazon resource name of the OpenSearch domain. Eg., `arn:aws:es:...` 3. `$endpoint` - The connection endpoint in `address:port` format. 4. `$address` - DNS address of the OpenSearch domain (e.g., `search-mydomain-xxxxx.us-east-1.es.amazonaws.com`). 5. `$port` - The port your code will use to access the domain. OpenSearch is reached over HTTPS, so this is `443`. 6. `$username` - Username of the master user for fine-grained access control. 7. `$passwordArn` - Password of the master user `$username` is automatically generated, encrypted and maintained in AWS Secrets Manager. Your code can read the password from Secrets Manager using this `$passwordArn`. 8. `$password` - The plaintext password of the master user `$username`. LocalOps resolves the password from AWS Secrets Manager and injects it directly as an environment variable, so your code can use it without calling the Secrets Manager API. Treat this value as a secret. 9. `$dsn` - Ready-to-use connection string for the domain, in the form `https://$username:$password@$address:443`. Convenient for OpenSearch clients/libraries that accept a single connection URL. Treat this value as a secret since it embeds the password. ### Lifecycle: If you have provided `ops.json` at the root of the git repository, it will be processed if a corresponding service in any of your active environment points at the same repository as source and when a deployment is triggered. * When the service is spinned up first time or when a new deployment is triggered, `ops.json` is parsed for processing. Resources declared in the `dependencies` object will be provisioned before your code starts to run. * Resources with same `id` are provisioned only once for the life of the service. And updated when there is a change in one of the properties above. * Keys in `exports` object will be passed as enviroment variables to your service. * When the service is deleted, the provisioned OpenSearch domains are deleted from the cloud account immediately & automatically. ### Private only access: OpenSearch domains can be accessed from your code using your favorite OpenSearch client library over HTTPS. When `publicly_accessible` is `false` (the default), the domain is attached to your environment's VPC. Its network interfaces are placed in the private subnets and protected with a security group that allows: 1. From source: `10.0.0.0/16` (Your environment's VPC CIDR IP range) 2. At port: `443` 3. Protocol: `TCP` So only workload/containers/servers from within your environment's VPC can reach the OpenSearch domain. When `publicly_accessible` is `true`, the domain is reachable from the public internet. The domain still enforces HTTPS-only access and requires the master user credentials for every request (see fine-grained access control below). ### Reading Master user password: LocalOps generates a unique random password for the master user and stores it - along with the username - as a JSON document `{"username":"...","password":"..."}` in AWS Secrets Manager. The first deployment writes the secret; later deployments do not overwrite it, so the password is stable across re-deploys. You can either capture the ARN of this secret using `$passwordArn` and read the JSON from Secrets Manager using the AWS SDK, or use `$password` / `$dsn` to receive the resolved password directly as an environment variable. ### Pre-configured for production use: All OpenSearch domains provisioned via `ops.json` are tuned for production by default. LocalOps handles the AWS plumbing that is easy to get wrong and applies the following on every domain: **High availability & quorum** 1. Defaults to **3 data nodes** so the cluster forms a 3-way quorum and tolerates a single node failure. 2. Spreads nodes across **multiple Availability Zones** with zone awareness. LocalOps picks 3 AZs if `node_count` is a multiple of 3, else 2 AZs if it is a multiple of 2 - matching AWS's requirement that `instance_count` divide evenly by `availability_zone_count`. The required number of private subnets must exist in your environment's space; the deployment fails with a clear error if it doesn't. 3. **Rejects 2-node production clusters without dedicated masters**, since such a cluster loses quorum on any single node failure. 4. When `dedicated_master` is `true`, provisions **3 dedicated master nodes** (the AWS-recommended count) so master-eligible workload is isolated from data nodes. **Encryption & transport** 1. **Encryption at rest** is enabled (free; applied even in preview environments). 2. **Node-to-node encryption** is enabled so inter-node traffic is encrypted in transit. 3. **HTTPS-only** access with a **TLS 1.2 minimum** security policy (`Policy-Min-TLS-1-2-2019-07`). **Authentication & authorization** 1. **Fine-grained access control (FGAC)** is enabled with the **internal user database**, so the domain is locked behind a master user from the moment it comes up. 2. Master user credentials are auto-generated and stored in **AWS Secrets Manager**. The application service role is granted `secretsmanager:GetSecretValue` and `secretsmanager:DescribeSecret` on that secret, and `es:ESHttp*`, `es:DescribeDomain`, `es:DescribeDomainConfig` on the domain. 3. The domain's resource policy allows the action surface (`es:*`) on the domain; **FGAC is the actual auth gate**. **Observability** In non-preview environments, LocalOps creates two CloudWatch log groups per domain (30-day retention) and publishes: 1. `INDEX_SLOW_LOGS`, `SEARCH_SLOW_LOGS`, `ES_APPLICATION_LOGS` to the general log group. 2. `AUDIT_LOGS` to a separate audit log group. Audit logs require FGAC (already enabled) and record every authentication/authorization event - critical for compliance and forensics. A single CloudWatch resource policy grants `es.amazonaws.com` write access to both log groups, keeping you under the per-region 10-policy CloudWatch limit even with many domains. **Safe updates & rename protection** 1. The underlying **domain name is locked** after creation. Renaming the dependency `id` in `ops.json` is a no-op on the live domain - it does not force a replacement that would destroy all indexed data. To actually replace a domain, delete the dependency and add a new one. 2. The Secrets Manager **secret version is locked** after the first deployment, so re-deploys never rotate the master password silently. 3. `engine_version` changes are **not** ignored - bumping the version in `ops.json` flows through as an in-place engine upgrade. **Service prerequisites** LocalOps automatically ensures the `AWSServiceRoleForAmazonOpenSearchService` service-linked role exists in your AWS account before provisioning the first VPC-attached domain. AWS requires this role; LocalOps creates it on your behalf. ### Ephemeral preview environments: For speed and cost savings, the following are scaled down in ephemeral services created for [pull request previews](https://localops.co/blog/introducing-pull-request-previews): 1. `node_count` is forced to `1` regardless of the `ops.json` value. 2. Zone awareness is disabled (single AZ). 3. `dedicated_master` is ignored. 4. CloudWatch log publishing (slow logs, app logs, audit logs) is **not** configured. Encryption at rest, node-to-node encryption, HTTPS enforcement and fine-grained access control remain enabled in preview environments as well. # RDS (Postgres, MySQL & SQL Server) Source: https://docs.localops.co/environment/services/aws/rds Provision Amazon RDS databases - Postgres/MySQL/SQL Server Your service(s) may want to store/access data in a Postgres, MySQL or SQL Server database. This guide will show you steps to create and access Amazon RDS databases that offer fully managed Postgres, MySQL and SQL Server databases. ## Declarative & Automatic using `ops.json`: For your service, if you need one or more RDS instances, you can add `ops.json` in the root directory of Github repo you've connected for the service. > [!TIP] > > Learn more about configuring dependencies using `ops.json`[here](/environment/services/ops-json). And add RDS instances as a dependency, like below. ```json theme={null} { "dependencies": { "rds": { "instances": [ { "id": "test123", "prefix": "testdep123", "engine": "postgres", "version": "17.5", "storage_gb": 10, "instance_type": "db.t4g.small", "publicly_accessible": false, "managed_password": true, "parameters": [ { "name": "shared_preload_libraries", "value": "pg_stat_statements,pg_cron", "apply_method": "pending-reboot" } ], "exports": { "MY_RDS_INSTANCE_NAME": "$name", "MY_RDS_INSTANCE_ARN": "$arn", "MY_RDS_INSTANCE_ENDPOINT": "$endpoint", "MY_RDS_INSTANCE_ADDRESS": "$address", "MY_RDS_INSTANCE_USERNAME": "$username", "MY_RDS_INSTANCE_PASSWORD_ARN": "$passwordArn", "MY_RDS_INSTANCE_PASSWORD": "$password", "MY_RDS_INSTANCE_DB_NAME": "$dbName", "MY_RDS_INSTANCE_DSN": "$dsn" } } ] } } } ``` You can add as many RDS instances as you want. Arguments you can add in each instance object above: 1. `id` - Alphanumeric string. Must be unique amongst the instances you've declared above. Changing this string will replace the original instance with new one. 2. `prefix` - Alphanumeric string. Will be used as a prefix in the name of your instance. Changing this string will replace the original instance with new instance. 3. `engine` - Provide one of `postgres`, `mysql`, `sqlserver-ex`, `sqlserver-web`, `sqlserver-se` or `sqlserver-ee`. Default: `postgres`. The four `sqlserver-*` values are the SQL Server editions - see [SQL Server](#sql-server) below. 4. `version` - Pick a version for your database. Ensure RDS supports it, by referring to AWS docs - [Postgres](https://docs.aws.amazon.com/AmazonRDS/latest/PostgreSQLReleaseNotes/postgresql-versions.html) / [MySQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/MySQL.Concepts.VersionMgmt.html) / [SQL Server](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/SQLServer.Concepts.General.VersionSupport.html). Default: `""` - so it will provision latest version as decided by AWS. 5. `storage_gb` - Specify the amount of storage you need in GB. You can set one value and yet change this later. Default: `10`, or `20` for SQL Server, which also needs at least `20`. 6. `instance_type` - Specify any class of instance in the following groups - "db.t4g.*", "db.t3.*", "db.m5.\*". Refer to [AWS docs](https://aws.amazon.com/rds/instance-types/) for available sizes. Default: `db.t4g.small`, or `db.t3.small` for `sqlserver-ex` and `sqlserver-web`. Required for `sqlserver-se` and `sqlserver-ee`. 7. `publicly_accessible` - Set it to `true` if you need this database to be available publicly on the internet. You would want this to be `false` most of the time. Default: `false` 8. `multi_az` - Specifies if the RDS instance is multi-AZ. Not supported for `sqlserver-ex` and `sqlserver-web`. 9. `maintenance_window` - The window to perform maintenance in. Syntax: "ddd:hh24:mi-ddd:hh24:mi". Eg: "Mon:00:00-Mon:03:00". See [RDS Maintenance Window docs](http://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_UpgradeDBInstance.Maintenance.html#AdjustingTheMaintenanceWindow) for more information. 10. `managed_password` - Controls who creates and stores the RDS master password. Default: `true`. * When `true` (recommended), AWS RDS generates the master password and stores it in its own AWS Secrets Manager entry, and RDS rotates it automatically over time. * When `false`, LocalOps generates a cryptographically unique password string and sets it as the RDS master password. The password is not rotated, so the same value keeps being used for the life of the instance. Setting this to `false` is not recommended since keeping the same master password forever is less secure than letting RDS rotate it. Regardless of which mode you pick, use `$password` and `$dsn` in `exports` to fetch the current password and connection string - LocalOps resolves them transparently in both cases. 11. `parameters` - Optional list of DB parameter group settings to apply to the RDS instance. Each entry is an object with the following keys: * `name` - Name of the parameter (e.g., `shared_preload_libraries`, `max_connections`). Must be a valid parameter for the chosen `engine` and `version`. Refer to the [Postgres parameter docs](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.Parameters.html) or [MySQL parameter docs](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_WorkingWithParamGroups.html) for available names. * `value` - Value to set for the parameter. Always specified as a string. * `apply_method` - When the change should take effect. Required. One of `immediate` or `pending-reboot`. Use `pending-reboot` for parameters that require a database restart (such as `shared_preload_libraries`). When `parameters` is provided, LocalOps creates a dedicated DB parameter group for the instance and attaches it. Adding, updating or removing entries on subsequent deployments updates the parameter group in-place. 12. `exports` - Set of key value pairs. Keys are the ENVIRONMENT VARS we will pass to your code / containers. Values are the properties of the RDS instance provisioned. See below for available properties. > [!WARNING] > > Changing `id` or `prefix` string will delete & replace the original RDS instance with new one. Available properties of the RDS instance to use in `exports`: 1. `$name` - Name of the RDS instance 2. `$arn` - Amazon resource name of the RDS instance. Eg., `arn:rds:..` 3. `$endpoint` - The connection endpoint in `address:port` format. 4. `$address` - Specifies the DNS address of the DB instance. 5. `$dbName` - Specifies the database name created under the RDS instance. This is auto-created for you so you won't specific this name explicitly anywhere in your config. Not available for SQL Server, where RDS creates no database. 6. `$username` - Specifics the username of the database user. You will typically use this in your code's Db connection string to access the database `$dbName`. 7. `$passwordArn` - Password of the user `$username` is automatically generated, encrypted and maintained by RDS in AWS secret manager. Your code has to read the password from the AWS secret manager using this `$passwordArn`. 8. `$password` - The plaintext password of the user `$username`. LocalOps resolves the password from AWS Secrets Manager and injects it directly as an environment variable, so your code can use it without calling the Secrets Manager API. Treat this value as a secret. 9. `$dsn` - Ready-to-use database connection string for the instance, in the standard URL form for the chosen engine (e.g., `postgres://$username:$password@$address:5432/$dbName` for Postgres, `mysql://$username:$password@$address:3306/$dbName` for MySQL or `sqlserver://$username:$password@$address:1433` for SQL Server). Convenient for libraries/ORMs that accept a single connection URL. Treat this value as a secret since it embeds the password. ### SQL Server: Set `engine` to the SQL Server edition you need. RDS provisions it with the license included, so there is no license of your own to bring. | `engine` | Edition | Default `instance_type` | Multi-AZ | Encryption at rest | | - | - | - | - | - | | `sqlserver-ex` | Express | `db.t3.small` | No | No | | `sqlserver-web` | Web | `db.t3.small` | No | Yes | | `sqlserver-se` | Standard | None - set it yourself | Yes | Yes | | `sqlserver-ee` | Enterprise | None - set it yourself | Yes | Yes | ```json theme={null} { "dependencies": { "rds": { "instances": [ { "id": "ledger", "prefix": "ledger", "engine": "sqlserver-ex", "storage_gb": 20, "exports": { "MSSQL_URL": "$dsn", "MSSQL_HOST": "$address", "MSSQL_USERNAME": "$username", "MSSQL_PASSWORD": "$password" } } ] } } } ``` RDS creates no database on a SQL Server instance, so `$dbName` is not available and `$dsn` carries no database name - create the databases your service needs yourself, for example from an init job. Declaring `$dbName` in `exports`, or `multi_az` on an edition that does not support it, fails the deployment with an error naming the setting. ### Lifecycle: If you have provided `ops.json` at the root of the git repository, it will be processed if a corresponding service in any of your active environment points at the same repository as source and when a deployment is triggered. * When the service is spinned up first time or when a new deployment is triggered, `ops.json` is parsed for processing. Resources declared in the `dependencies` object will be provisioned before your code starts to run. * Resources with same `id` are provisioned only once for the life of the service. And updated when there is a change in one of the properties above. * Keys in `exports` object will be passed as enviroment variables to your service. * When the service is deleted, the provisioned RDS instances are deleted from the cloud account immediately & automatically. ### Private only access: RDS databases can be accessed from your code just as usual using your SQL-compatible DB libraries or ORMs. All RDS instances are created only in the private subnets of the same VPC where your environment is running. And they are attached with following security group. Ingress: 1. From source: `10.0.0.0/16` (Your environment's VPC CIDR IP range) 2. At port: `5432` (for Postgres), `3306` (for MySQL) or `1433` (for SQL Server) 3. Protocol: `TCP` So only workload/containers/servers from within your environment's VPC can access the RDS instance. This means you cannot point `psql` or a desktop SQL client at the database directly from your laptop. To get an interactive SQL shell, or to reach the database from a GUI client, connect from inside the cluster using the LocalOps CLI - see [Connect to your database](/cli/usage#connect-to-your-databases-or-cache). ### Reading Database password: By default (`managed_password: true`), RDS creates and encrypts a unique random password and stores it in your AWS account's Secrets Manager, and rotates it automatically. You can capture the ARN of this secret under an environment variable like shown above and fetch the password value using AWS SDK. If you set `managed_password: false`, LocalOps generates a cryptographically unique string and uses it as the RDS master password instead. This password is not rotated, which is why `managed_password: true` is the recommended setting. In both modes, you can use `$password` to receive the resolved plaintext password as an environment variable, or `$dsn` for a ready-to-use connection string - LocalOps handles the resolution for you regardless of which mode the instance was created in. When `managed_password: true`, RDS rotates the password periodically, so the `$password` and `$dsn` values injected at container start can go stale between rotations. Also export `$passwordArn` and have your code fall back to reading the current password from AWS Secrets Manager using that ARN whenever a DB connection fails with a bad-password / auth error, then retry the connection with the freshly fetched password. ### Pre-configured for production use: All RDS instances are pre-configured for production use. 1. Daily backup is enabled. With 30-day retention for each backup. 2. Encryption is enabled to safeguard data at rest. SQL Server Express (`sqlserver-ex`) is the exception, as RDS does not support encryption for that edition. 3. Backup is created automatically when the instance is about to get deleted. For speed and cost savings reasons, all the above are turned off in ephemeral services we create in the case of [pull request previews](https://localops.co/blog/introducing-pull-request-previews). ## Manually provision new RDS Instance: To proceed with this guide, you would need access to: 1. AWS console with permissions to create RDS database 2. LocalOps console Goal is to create a RDS database in AWS and give your environment/service(s) access to it. Please follow the steps below to proceed: ### 1. Fetch the VPC and private subnet IDs To give your environment and service(s) access to a RDS database, you need to create the RDS database within the same VPC and region used by the environment. Navigate to LocalOps console and the environment you created. In the environment's overview section, 1. Pick/copy the VPC ID and Private Subnet IDs 2. Note down the region You will use these in the next step while creating the RDS database. ### 2. Create RDS database Login to the same AWS account and region where you created the environment using LocalOps. And create new RDS database with appropriate engine - Postgres/MySQL/SQL Server. You will have to create a new subnet group first before creating the RDS instance. While creating the subnet group, use the VPC ID and private subnet IDs you copied above. > [!TIP] > > For the same app, if you already have a RDS database in a different AWS account, different VPC or in a different > region, you can very well use the same and skip creating a new RDS database. We can connect your environment/services > and the database via VPC peering. Learn more about using an existing database below. For rest of the instructions, you can follow this [official AWS guide](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_CreateDBInstance.html) to create your database. Record the database endpoint, username and password. ### 3. Add DB endpoint and credentials as secrets Last step is to give your service(s) access to the RDS database. In LocalOps console, navigate the Service settings within the corresponding environment. In secrets section, add a new key value pair like ``` - Key: `DB_HOST` - Value: `your-db-endpoint` - Key: `DB_USERNAME` - Value: `your-db-username` - Key: `DB_PASS` - Value: `your-db-password` ``` Learn more about secrets [here](/environment/services/secrets). You can name the key in any way you want. In your code, you can access `DB_*` environment variables to connect and access the database. Repeat the above process for each RDS instance you want to create for each environment - test, staging, production, etc., That's it! ## Use pre-existing RDS Instance ### 1. Setup VPC peering Your LocalOps environment is created in its own VPC in the chosen AWS account and region. For the same application, if you already have a RDS database instance running in the same/different AWS account, you can connect/access it with the corresponding LocalOps environment using Amazon VPC peering. VPC peering lets you connect two VPCs from same or different AWS account/region so that resources in one VPC can access the resources in another VPC like they belong to the same network. Ping us on slack / write to us at [support@localops.co](mailto:support@localops.co) / [book a call](https://go.localops.co/meet-engineer) with our team to guide you on this. ### 2. Add DB endpoint and credentials as secrets Last step is to give your service(s) access to the RDS database. In LocalOps console, navigate the Service settings within the corresponding environment. In secrets section, add a new key value pair like ``` - Key: `DB_HOST` - Value: `your-db-endpoint` - Key: `DB_USERNAME` - Value: `your-db-username` - Key: `DB_PASS` - Value: `your-db-password` ``` Learn more about secrets [here](/environment/services/secrets). You can name the key in any way you want. In your code, you can access `DB_*` environment variables to connect and access the database. That's it. 🎉 # S3 Buckets Source: https://docs.localops.co/environment/services/aws/s3 Provision S3 buckets as object storage for files and attachments Your service(s) may want to store/access files in S3. This guide will show you steps to create and access s3 buckets from your services. ## Declarative & Automatic using `ops.json`: For your service, if you need one or more S3 buckets, you can add `ops.json` in the root directory of Github repo you've connected for the service. > [!TIP] > > Learn more about configuring dependencies using `ops.json`[here](/environment/services/ops-json). And add S3 buckets as a dependency, like below. ```json theme={null} { "dependencies": { "s3": { "buckets": [ { "id": "test123", "prefix": "testdep123", "exports": { "MY_BUCKET_NAME1": "$name", "MY_BUCKET_ARN1": "$arn" } } ] } } } ``` You can add as many buckets as you want. Arguments you can add in each bucket object above: 1. `id` - Alphanumeric string. Must be unique amongst the buckets you've declared above. Changing this string will replace the original bucket with new one. 2. `prefix` - Alphanumeric string. Will be used as a prefix in the name of your bucket. Changing this string will replace the original bucket with new bucket. 3. `exports` - Set of key value pairs. Keys are the ENVIRONMENT VARS we will pass to your code / containers. Values are the properties of the bucket provisioned. See below for available properties. > [!WARNING] > > Changing `id` or `prefix` string will delete & replace the original bucket with new one. Available properties of the bucket to use in `exports`: 1. `$name` - Name of the bucket 2. `$arn` - Amazon resource name of the bucket. Eg., `arn:s3:..` ### Lifecycle: If you have provided `ops.json` at the root of the git repository, it will be processed if a corresponding service in any of your active environment points at the same repository as source and when a deployment is triggered. * When the service is spinned up first time or when a new deployment is triggered, `ops.json` is parsed for processing. Resources declared in the `dependencies` object will be provisioned before your code starts to run. * Resources with same `id` are provisioned only once for the life of the service. And updated when there is a change in one of the properties above. * Keys in `exports` object will be passed as enviroment variables to your service. * When the service is deleted, the provisioned buckets are deleted from the cloud account immediately & automatically. ### Access with no keys: Buckets can be accessed from your code using AWS SDK. You don't have to pass any AWS secret key to authenticate. Your containers automatically authenticate to have access to all the buckets you've declared in the above JSON. LocalOps arranges Role based access by attaching an IAM role for all the services run within your environment. We provision a policy like below on that IAM role for every bucket provisioned. ``` { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::your-bucket-name", "arn:aws:s3:::your-bucket-name/*" ] } ``` Curious to know the IAM role that is used? Visit your environment's main dashboard in LocalOps console to see the role. ## Manual provisioning of new S3 buckets: To proceed with this guide, you would need access to: 1. AWS console with permissions to create s3 buckets and add policies to an existing IAM role. 2. LocalOps console ### 1. Create S3 bucket Login to AWS console and create new S3 bucket(s) in the region you want, and with appopriate unique name. You can follow this [official AWS guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/GetStartedWithS3.html#creating-bucket) to create s3 buckets. ### 2. Add permission to access S3 bucket LocalOps creates a new IAM role in your AWS account for your services/containers to use. So that your code/containers can access any AWS resource without passing AWS\_ACCESS\_KEY or AWS\_SECRET\_KEY. Navigate to LocalOps console and the corresponding environment. In overview section, you can find the APP ROLE whose name ends with `app-role` and that which you can copy and search in AWS IAM console > Roles section. Once you find the IAM role in IAM console, next step is to add a policy to the IAM role to give permissions for the role to access the S3 bucket your created. #### Create a new IAM policy for the S3 bucket: 1. Navigate to Policies in AWS IAM console 2. Create a new IAM policy and give it a specific name 3. Add the JSON below, as policy statement: ``` { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::your-bucket-name", "arn:aws:s3:::your-bucket-name/*" ] } ``` Replace `your-bucket-name` with your bucket name. 4. Press save. #### Add the new IAM policy to the IAM role Navigate back to the IAM role you saw earlier. In its Permissions tab, pick the option to "Add Policy". In the policy picker, pick the one you created above and add it. ### 3. Add bucket details as secret Last step is to tell your service about the new S3 bucket it can start to access. In LocalOps console, navigate the Service settings within the corresponding environment. In secrets section, add a new key value pair like ``` - Key: `attachments-bucket` - Value: `your-bucket-name` ``` Learn more about secrets [here](/environment/services/secrets). You can name the key in any way you want. In your code, you can access `attachments-bucket` environment variable to get the name of the bucket you created. This can be passed to the AWS SDK used in your code to read/write data. There is no need to provide credentials like access key since we are having role based access control here. That's it! 🎉 # SNS Topics Source: https://docs.localops.co/environment/services/aws/sns Provision Amazon SNS topics for pub/sub communication This guide will show you steps to create SNS topics and access them from your service running within environments. ## Declarative & Automatic using `ops.json`: For your service, if you need one or more SNS topics, you can add `ops.json` in the root directory of Github repo you've connected for the service. > [!TIP] > > Learn more about configuring dependencies using `ops.json`[here](/environment/services/ops-json). And add SNS topics as a dependency, like below. ```json theme={null} { "dependencies": { "sns": { "topics": [ { "id": "test123", "prefix": "testdep123", "exports": { "MY_SNS_TOPIC_NAME1": "$name", "MY_SNS_TOPIC_ARN1": "$arn" } } ] } } } ``` You can add as many topics as you want. Arguments you can add in each topic object above: 1. `id` - Alphanumeric string. Must be unique amongst the Topics you've declared above. Changing this string will replace the original topic with new one. 2. `prefix` - Alphanumeric string. Will be used as a prefix in the name of your topic. Changing this string will replace the original topic with new topic. 3. `exports` - Set of key value pairs. Keys are the ENVIRONMENT VARS we will pass to your code / containers. Values are the properties of the Topic provisioned. See below for available properties. > [!WARNING] > > Changing `id` or `prefix` string will delete & replace the original topic with new one. Available properties of the topic to use in `exports`: 1. `$name` - Name of the topic 2. `$arn` - Amazon resource name of the topic. Eg., `arn:sns:..` ### Lifecycle: If you have provided `ops.json` at the root of the git repository, it will be processed if a corresponding service in any of your active environment points at the same repository as source and when a deployment is triggered. * When the service is spinned up first time or when a new deployment is triggered, `ops.json` is parsed for processing. Resources declared in the `dependencies` object will be provisioned before your code starts to run. * Resources with same `id` are provisioned only once for the life of the service. And updated when there is a change in one of the properties above. * Keys in `exports` object will be passed as enviroment variables to your service. * When the service is deleted, the provisioned resources (topics, here) are deleted from the cloud account immediately & automatically. ### Access with no keys: Topics can be accessed from your code using AWS SDK. You don't have to pass any AWS secret key to authenticate. Your containers automatically authenticate to have access to all the topics you've declared in the above JSON. LocalOps arranges Role based access by attaching an IAM role for all the services run within your environment. We provision a policy like below on that IAM role for every Topic provisioned. ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sns:Publish", "sns:Subscribe", "sns:Unsubscribe", "sns:Receive", "sns:GetTopicAttributes", "sns:SetTopicAttributes", "sns:ListSubscriptionsByTopic" ], "Resource": "your-sns-topic" } ] } ``` Curious to know the IAM role that is used? Visit your environment's main dashboard in LocalOps console to see the role. ## Manual provisioning of new SNS topics: To proceed with this guide, you would need access to: 1. AWS console with permissions to access SNS console and add policies to an existing IAM role. 2. LocalOps console ### 1. Create SNS topic Login to AWS console and create new SNS topic in the region you want, and with appopriate unique name. You can follow this [official AWS guide](https://docs.aws.amazon.com/sns/latest/dg/sns-getting-started.html) to create SNS topic(s). ### 2. Add permission to access SNS topic LocalOps creates a new IAM role in your AWS account, for each environment, so that your services/containers can access them. So that your code/containers can access any AWS resource without passing AWS\_ACCESS\_KEY or AWS\_SECRET\_KEY. Navigate to LocalOps console and the corresponding environment. In overview section, you can find the APP ROLE whose name ends with `app-role` and that which you can copy and search in AWS IAM console > Roles section. Once you find the IAM role in IAM console, next step is to add a policy to the IAM role to give permissions for the role to access the SNS topic(s) your created. #### Create a new IAM policy for the SNS topic: 1. Navigate to Policies in AWS IAM console 2. Create a new IAM policy and give it a specific name 3. Add the JSON below, as policy statement: ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sns:Publish", "sns:Subscribe", "sns:Unsubscribe", "sns:Receive", "sns:GetTopicAttributes", "sns:SetTopicAttributes", "sns:ListSubscriptionsByTopic" ], "Resource": "" } ] } ``` Replace `` with your SNS topic's ARN. If you create more than one topic, expand the `Resource` attribute above to an array of ARN strings. 4. Press save. #### Add the new IAM policy to the IAM role Navigate back to the IAM role you saw earlier. In its Permissions tab, pick the option to "Add Policy". In the policy picker, pick the one you created above and add it. ### 3. Add topic details as secret Last step is to give service access to the new SNS topic. In LocalOps console, navigate to the Service settings within the corresponding environment. In secrets section, add a new key value pair like ``` - Key: `topic-var-name` - Value: `topic-name` ``` Repeat this for each topic you created. Learn more about secrets [here](/environment/services/secrets). You can name the key in any way you want. In your code, you can access `topic-var-name` environment variable to get the name of the topic you created. This can be passed to the AWS SDK used in your code to read/write data. There is no need to provide credentials like access key since we are having role based access control here. That's it! 🎉 # SQS Queues Source: https://docs.localops.co/environment/services/aws/sqs Provision queues - Standard/FIFO in AWS Amazon SQS offers fully managed FIFO / standard queues. Your service(s) may want to add items/jobs/messages to a queue and process them later. This guide will show you steps to create and access Amazon SQS queues from your services. ## Declarative & Automatic using `ops.json`: For your service, if you need one or more SQS queues, you can add `ops.json` in the root directory of Github repo you've connected for the service. > [!TIP] > > Learn more about configuring dependencies using `ops.json`[here](/environment/services/ops-json). And add SQS queues as a dependency, like below. ```json theme={null} { "dependencies": { "sqs": { "queues": [ { "id": "test123", "prefix": "testdep123", "fifo": true, "exports": { "MY_SQS_QUEUE_NAME1": "$name", "MY_SQS_QUEUE_ARN1": "$arn" } } ] } } } ``` You can add as many queues as you want. Arguments you can add in each queue object above: 1. `id` - Alphanumeric string. Must be unique amongst the queues you've declared above. Changing this string will replace the original queue with new one. 2. `prefix` - Alphanumeric string. Will be used as a prefix in the name of your queue. Changing this string will replace the original queue with new queue. 3. `fifo` - Set this to `true` if you need a FIFO queue. Set it to false or leave out the fifo key if you want a standard queue instead. 4. `exports` - Set of key value pairs. Keys are the ENVIRONMENT VARS we will pass to your code / containers. Values are the properties of the queue provisioned. See below for available properties. > [!WARNING] > > Changing `id` or `prefix` string will replace the original queue with new one. Available properties of the queue to use in `exports`: 1. `$name` - Name of the queue 2. `$arn` - Amazon resource name of the queue. Eg., `arn:sqs:..` ### Lifecycle: If you have provided `ops.json` at the root of the git repository, it will be processed if a corresponding service in any of your active environment points at the same repository as source and when a deployment is triggered. * When the service is spinned up first time or when a new deployment is triggered, `ops.json` is parsed for processing. Resources declared in the `dependencies` object will be provisioned before your code starts to run. * Resources with same `id` are provisioned only once for the life of the service. And updated when there is a change in one of the properties above. * Keys in `exports` object will be passed as enviroment variables to your service. * When the service is deleted, the provisioned queues are deleted from the cloud account immediately & automatically. ### Access with no keys: Queues can be accessed from your code using AWS SDK. You don't have to pass any AWS secret key to authenticate. Your containers automatically authenticate to have access to all the queues you've declared in the above JSON. LocalOps arranges Role based access by attaching an IAM role for all the services run within your environment. We provision a policy like below on that IAM role for every queue provisioned. ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sqs:SendMessage", "sqs:ReceiveMessage", "sqs:DeleteMessage", "sqs:GetQueueAttributes", "sqs:GetQueueUrl", "sqs:ChangeMessageVisibility" ], "Resource": "your-queue" } ] } ``` Curious to know the IAM role that is used? Visit your environment's main dashboard in LocalOps console to see the role. ## Manual provisioning of new SQS queues: To proceed with this guide, you would need access to: 1. AWS console with permissions to create SQS queues and add policies to an existing IAM role. 2. LocalOps console ### 1. Create SQS queue Login to AWS console and create new SQS queue in the region you want, and with appopriate unique name. You can follow this [official AWS guide](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/creating-sqs-standard-queues.html) to create a sqs queue. ### 2. Add permission to access SQS queue LocalOps creates a new IAM role in your AWS account for your services/containers to use. So that your code/containers can access any AWS resource without passing AWS\_ACCESS\_KEY or AWS\_SECRET\_KEY. Navigate to LocalOps console and the corresponding environment. In overview section, you can find the APP ROLE whose name ends with `app-role` and that which you can copy and search in AWS IAM console > Roles section. Once you find the IAM role in IAM console, next step is to add a policy to the IAM role to give permissions for the role to access the SQS queue your created. #### Create a new IAM policy for the SQS queue: 1. Navigate to Policies in AWS IAM console 2. Create a new IAM policy and give it a specific name 3. Add the JSON below, as policy statement: ```json theme={null} { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sqs:SendMessage", "sqs:ReceiveMessage", "sqs:DeleteMessage", "sqs:GetQueueAttributes", "sqs:GetQueueUrl", "sqs:ChangeMessageVisibility" ], "Resource": "" } ] } ``` Replace `` with your SQS queue's ARN. If you create more than one queue, expand the `Resource` attribute above to an array of ARN strings. 4. Press save. #### Add the new IAM policy to the IAM role Navigate back to the IAM role you saw earlier. In its Permissions tab, pick the option to "Add Policy". In the policy picker, pick the one you created above and add it. ### 3. Add queue details as secret Last step is to give service access to the new SQS queue. In LocalOps console, navigate to the Service settings within the corresponding environment. In secrets section, add a new key value pair like ``` - Key: `queue-var-name` - Value: `queue-name` ``` Repeat this for each queue you created. Learn more about secrets [here](/environment/services/secrets). You can name the key in any way you want. In your code, you can access `queue-var-name` environment variable to get the name of the queue you created. This can be passed to the AWS SDK used in your code to read/write data. There is no need to provide credentials like access key since we are having role based access control here. That's it! 🎉 # BEAM clustering Source: https://docs.localops.co/environment/services/beam-clustering Cluster your Elixir/Erlang services with a single ops.json key so nodes discover each other over distributed Erlang. Elixir and Erlang applications often need their nodes to find each other — to hand work to a peer, to run a distributed registry, or to broadcast over Phoenix PubSub. On LocalOps, you get there by adding one key to `ops.json` in each service that should be part of the cluster. > [!NOTE] > > This page assumes your service is already deploying on LocalOps. If you're still packaging your app, start with the > [Elixir/Phoenix guide](/guides/languages/elixir). ## Enable it ```json ops.json theme={null} { "beam_cluster_id": "myapp" } ``` Use the same value in every service you want clustered together — your web service, your worker, your internal RPC service. LocalOps then labels all their pods alike and creates a shared headless service whose DNS returns every member pod's IP. ## What LocalOps injects Two environment variables are injected into your pods: | Variable | Value | | - | - | | `LOPS_BEAM_CLUSTER_NAME` | `myapp` | | `LOPS_BEAM_CLUSTER_DNS` | `myapp-cluster.app-services.svc.cluster.local` | `app-services` is the Kubernetes namespace all your services run in within the environment. ## Wire up libcluster Read the DNS name from the environment — don't hardcode it. ```elixir config/runtime.exs theme={null} config :libcluster, topologies: [ k8s: [ strategy: Cluster.Strategy.Kubernetes.DNS, config: [ service: System.get_env("LOPS_BEAM_CLUSTER_DNS"), application_name: "myapp", polling_interval: 5_000 ] ] ] ``` > [!WARNING] > > Always read `LOPS_BEAM_CLUSTER_DNS` at run time. The DNS name is derived from your `beam_cluster_id` and differs > between your production environment and each preview environment, so a hardcoded value will silently fail to find > peers somewhere. ## Your release config stays yours LocalOps does not set `RELEASE_DISTRIBUTION`, `RELEASE_NODE`, or `RELEASE_COOKIE`. Set these yourself — typically `RELEASE_DISTRIBUTION=name` with `RELEASE_NODE=myapp@${POD_IP}`. `POD_IP` is already injected into every service, so you can reference it directly. > [!WARNING] > > Use the same `RELEASE_COOKIE` across every service in the cluster, or nodes will refuse each other. Add it as a > [secret](/environment/services/secrets) with the same value in each service. ## Cluster across regions The headless service above only resolves inside one environment's Kubernetes cluster, so nodes in your Mumbai environment can't see nodes in Ireland. To form a single mesh across regional environments, give each environment a DNS name in a private zone that every regional VPC can resolve, and let LocalOps keep that name pointed at the environment's pods. > [!NOTE] > > The steps below use Mumbai (`ap-south-1`) and Ireland (`eu-west-1`) as example regions. Substitute the regions, > CIDRs, and names that fit your setup. **1. Spin up an environment in each region** In LocalOps, [create an environment](/environment/create) in every region the cluster should span — say one in `ap-south-1` (Mumbai) and one in `eu-west-1` (Ireland) — and deploy the same services to each. Every environment gets its own VPC, and by default every VPC uses `10.0.0.0/16`. Peered VPCs can't have overlapping CIDRs, so open **Advanced options** on the Create environment page and give each environment its own block — for example `10.10.0.0/16` for Mumbai and `10.20.0.0/16` for Ireland. > [!WARNING] > > The CIDR is fixed once the environment is created. An existing environment on the default `10.0.0.0/16` can't be > peered with another one on the same range — create a new environment with a distinct CIDR instead. **2. Set up VPC peering between the regions (AWS)** DNS gets nodes to each other's addresses; peering is what gets packets there. For every pair of regions: 1. **Request the peering connection.** In the VPC console of the first region (Mumbai), go to **Peering connections → Create peering connection**. Pick the Mumbai environment's VPC as the requester, choose **Another Region** (and **Another account**, if the environments live in different AWS accounts), and enter the Ireland environment's VPC ID. 2. **Accept it.** Switch the console to the other region (Ireland), open **Peering connections**, select the pending request, and choose **Actions → Accept request**. 3. **Update the private subnets' route tables, on both sides.** Your pods run in the environment's private subnets, so their route tables need a route to the peer VPC. In **Route tables**, filter by each environment's VPC and edit every route table associated with a private subnet — LocalOps creates one per availability zone — adding: | Environment | Destination | Target | | - | - | - | | Mumbai | `10.20.0.0/16` (Ireland) | the peering connection (`pcx-...`) | | Ireland | `10.10.0.0/16` (Mumbai) | the peering connection (`pcx-...`) | Leave the public subnets' route tables alone — nodes never talk across regions from there. Peering isn't transitive — with three regions you need three peering connections (Mumbai↔Ireland, Mumbai↔Virginia, Ireland↔Virginia), each with routes on both sides. Past a handful of regions, a Transit Gateway is simpler to manage than a full mesh of peerings. You can do the same from the CLI: ```bash theme={null} # In Mumbai: request aws ec2 create-vpc-peering-connection --region ap-south-1 \ --vpc-id vpc-mumbai --peer-vpc-id vpc-ireland --peer-region eu-west-1 # In Ireland: accept aws ec2 accept-vpc-peering-connection --region eu-west-1 --vpc-peering-connection-id pcx-0abc123 # Repeat for every private route table in each VPC aws ec2 create-route --region ap-south-1 --route-table-id rtb-mumbai-private-a \ --destination-cidr-block 10.20.0.0/16 --vpc-peering-connection-id pcx-0abc123 aws ec2 create-route --region eu-west-1 --route-table-id rtb-ireland-private-a \ --destination-cidr-block 10.10.0.0/16 --vpc-peering-connection-id pcx-0abc123 ``` **3. Open BEAM ports in the EKS cluster security groups** With peering in place, packets reach the other VPC but are dropped at the pods unless the security group allows them. Nodes need EPMD (TCP `4369`) plus the distribution ports open to the peer region. Erlang picks a random distribution port by default, so first pin it to a fixed range in your release config: ```elixir config/runtime.exs theme={null} config :kernel, inet_dist_listen_min: 9000, inet_dist_listen_max: 9010 ``` Then, in each region's VPC console, open **Security groups** and filter by the environment's VPC. LocalOps creates a security group along with the EKS cluster, and its name contains `eks-cluster` — that's the group attached to your pods. Add these inbound rules, with the **peer** region's CIDR as the source: | Security group | Type | Port range | Source | | - | - | - | - | | Mumbai `eks-cluster` | Custom TCP | `4369` | `10.20.0.0/16` (Ireland) | | Mumbai `eks-cluster` | Custom TCP | `9000-9010` | `10.20.0.0/16` (Ireland) | | Ireland `eks-cluster` | Custom TCP | `4369` | `10.10.0.0/16` (Mumbai) | | Ireland `eks-cluster` | Custom TCP | `9000-9010` | `10.10.0.0/16` (Mumbai) | With more regions, add the same pair of rules for each peer region's CIDR. > [!TIP] > > If nodes resolve each other's IPs but `Node.list()` stays empty, check these rules first — a missing rule shows > up as a connection timeout, not a DNS failure. **4. Create one private zone shared by every regional VPC** On AWS, create a Route 53 **private hosted zone** — say `mesh.acmecorp.internal` — and associate it with the VPC of every regional environment you spin up. One zone, many VPC associations. If your environments live in different AWS accounts, use cross-account zone association. On GCP, the equivalent is a Cloud DNS private zone with each regional VPC added to its visibility list. The zone has to be associated with a region's VPC *before* nodes there can resolve peers. **5. Give each environment a name in ops.json** Alongside `beam_cluster_id`, set `beam_dns_name` to the record this environment should own inside that zone: ```json ops.json theme={null} { "beam_cluster_id": "b2bapp", "beam_dns_name": "mumbai.mesh.acmecorp.internal" } ``` Keep `beam_cluster_id` identical everywhere — it's still what makes these nodes one cluster. `beam_dns_name` is per environment: `mumbai.mesh.acmecorp.internal` in Mumbai, `ireland.mesh.acmecorp.internal` in Ireland, and so on. LocalOps creates that record and keeps it in sync — it publishes the IPs of every pod in the environment carrying that `beam_cluster_id`, and updates the record as pods scale, restart, or get rescheduled. You don't manage the record set yourself. **6. List every region in your topologies** Add one topology per region so libcluster polls all of them. `LOPS_BEAM_CLUSTER_DNS` still points at the local headless service, so keep using it for this environment's own nodes and name the peer regions by their `beam_dns_name`: ```elixir config/runtime.exs theme={null} config :libcluster, topologies: [ local: [ strategy: Cluster.Strategy.Kubernetes.DNS, config: [ service: System.get_env("LOPS_BEAM_CLUSTER_DNS"), application_name: "b2bapp", polling_interval: 5_000 ] ], mum: [ strategy: Cluster.Strategy.Kubernetes.DNS, config: [ service: "mumbai.mesh.acmecorp.internal", application_name: "b2bapp", polling_interval: 5_000 ] ], ire: [ strategy: Cluster.Strategy.Kubernetes.DNS, config: [ service: "ireland.mesh.acmecorp.internal", application_name: "b2bapp", polling_interval: 5_000 ] ] ] ``` The same config ships to every region — each node finds its local peers through `LOPS_BEAM_CLUSTER_DNS` and every remote region through that region's record. Nodes connect from both ends, and the mesh forms. **7. Verify the mesh from one region** Once the new build is deployed in every region, use [`ops connect`](/cli/usage#shell-into-a-service) to open a shell on a pod in one region's environment: ```sh theme={null} ops connect --env mumbai --svc web ``` From that shell, attach a remote console to the running release and list the connected nodes: ```sh theme={null} bin/b2bapp remote ``` ```elixir theme={null} Node.list() ``` You should see nodes from every region, not just this one — for example `b2bapp@10.10.x.x` alongside `b2bapp@10.20.x.x`. If only local nodes show up, recheck the peering routes and the security group rules above. > [!WARNING] > > The `RELEASE_COOKIE` has to match across regions, not just across services in one region. > [!NOTE] > > Preview environments ignore `beam_dns_name`. They keep forming their own single-region cluster, for the same reason > they stay out of your production cluster. ## Things to know ### It takes effect on your next build LocalOps snapshots `ops.json` when it builds your service, so redeploying your current image won't pick up a newly added `beam_cluster_id`. Push the change and let it build. ### Preview environments get their own cluster A preview environment forms its own separate cluster and never joins your production cluster. This is deliberate — otherwise a preview would share your cookie and be able to call into live nodes. See [ephemeral databases and services for pull request previews](/environment/services/ops-json#ephemeral-databases-and-services-for-pull-request-previews). ### Job and cron services join too [Job](/environment/services/job) and [cron](/environment/services/cronjob) services join the cluster as well, so scheduled and one-off tasks can call into the running cluster. If you'd rather they stayed out, just leave `beam_cluster_id` out of those services' `ops.json`. > [!WARNING] > > Two caveats when they are in. Each run is a join-then-leave, which is a cluster-wide event — `:global` locks the > cluster on every `nodeup`, and Horde/Swarm rebalance their registries — so a frequent schedule means constant churn. > And those pods join as full peers, able to run code on any other node. ### Processes with their own image stay out A [`processes`](/environment/services/ops-json#configuring-processes) entry that specifies its own `image` stays out of the cluster, since it isn't running your app. ## Verify it worked Get a shell on a running pod with [`ops connect`](/cli/usage#shell-into-a-service), open a remote console, and run: ```sh theme={null} ops connect --env production --svc web bin/myapp remote ``` ```elixir theme={null} Node.list() ``` It should return your peers. The cluster's name is in `LOPS_BEAM_CLUSTER_NAME`. To watch inter-node distribution traffic over time, see the [Erlang & Elixir instrumentation guide](/environment/services/instrument/erlang) — the Erlang-Distribution Grafana dashboard it links is built for exactly this. # Client IP Source: https://docs.localops.co/environment/services/client-ip How to read the real client IP from incoming HTTP requests across direct, SSL-passthrough, and CDN setups. When your service handles an incoming HTTP request, the source IP on the TCP connection is rarely the real client. Requests traverse load balancers, SSL terminators, and (often) a CDN before they reach your container. Your environment ingress populates standard headers so your code can recover the real client IP — but which header to trust depends on how your service is fronted. ## Headers populated by your environment ingress | Header | Set by | Contains | | - | - | - | | `X-Real-IP` | Your environment ingress | A single IP that the ingress believes is the closest hop to the client. | | `X-Forwarded-For` | Your environment ingress (appended to) | Comma-separated list of IPs in the chain, left-most being the earliest. | ## Behavior across setups Different fronting setups leave these headers populated differently: | Setup | `X-Real-IP` | `X-Forwarded-For` | | - | - | - | | No CDN, HTTP | Real client | Real client | | No CDN, HTTPS (via SSL-passthrough multiplexer) | Real client (fixed) | Real client | | Behind CDN (public IPs) | CDN edge IP | `, ` | In the first two setups, both headers resolve to the real client and either is safe to use. In the third setup — when a CDN like Cloudflare, Fastly, or CloudFront sits in front of your service — your environment ingress sees the CDN edge IP on the connection. `X-Real-IP` will reflect that edge IP, not the real client. The real client IP shows up as the left-most entry in `X-Forwarded-For`, which the CDN populates before forwarding the request. ## Recommendation > [!TIP] > > If your service sits behind a CDN, read `X-Forwarded-For[0]` (the left-most entry) to get the real client IP. > Alternatively, use your CDN's own header — `CF-Connecting-IP` for Cloudflare, `True-Client-IP` for Akamai > / Cloudflare Enterprise, or `X-Forwarded-For` set by CloudFront. If you are not behind a CDN, `X-Real-IP` is the simplest and safest header to read. ## Examples ### Node.js (Express) ```js theme={null} app.get('/whoami', (req, res) => { // Behind a CDN: prefer the CDN's own header, then fall back to X-Forwarded-For[0]. const xff = req.headers['x-forwarded-for']; const clientIp = req.headers['cf-connecting-ip'] || req.headers['true-client-ip'] || (xff && xff.split(',')[0].trim()) || req.headers['x-real-ip'] || req.socket.remoteAddress; res.json({ clientIp }); }); ``` > **Python (FastAPI)** > > ```python theme={null} > from fastapi import FastAPI, Request > > app = FastAPI() > > @app.get('/whoami') > def whoami(request: Request): > headers = request.headers > xff = headers.get('x-forwarded-for') > client_ip = ( > headers.get('cf-connecting-ip') > or headers.get('true-client-ip') > or (xff.split(',')[0].strip() if xff else None) > or headers.get('x-real-ip') > or request.client.host > ) > return { 'clientIp': client_ip } > ``` > **Go (net/http)** > > ```go theme={null} > func whoami(w http.ResponseWriter, r *http.Request) { > clientIP := r.Header.Get("CF-Connecting-IP") > if clientIP == "" { > clientIP = r.Header.Get("True-Client-IP") > } > if clientIP == "" { > if xff := r.Header.Get("X-Forwarded-For"); xff != "" { > clientIP = strings.TrimSpace(strings.Split(xff, ",")[0]) > } > } > if clientIP == "" { > clientIP = r.Header.Get("X-Real-IP") > } > fmt.Fprintln(w, clientIP) > } > ``` > **Java (Spring Boot)** > > ```java theme={null} > @RestController > public class WhoamiController { > > @GetMapping("/whoami") > public String whoami(HttpServletRequest request) { > String clientIp = firstNonEmpty( > request.getHeader("CF-Connecting-IP"), > request.getHeader("True-Client-IP"), > firstXff(request.getHeader("X-Forwarded-For")), > request.getHeader("X-Real-IP"), > request.getRemoteAddr() > ); > return clientIp; > } > > private static String firstXff(String xff) { > if (xff == null || xff.isEmpty()) return null; > return xff.split(",")[0].trim(); > } > > private static String firstNonEmpty(String... values) { > for (String v : values) { > if (v != null && !v.isEmpty()) return v; > } > return null; > } > } > ``` > **.NET (ASP.NET Core)** > > ```csharp theme={null} > [ApiController] > [Route("whoami")] > public class WhoamiController : ControllerBase > { > [HttpGet] > public string Get() > { > var headers = Request.Headers; > > string clientIp = > headers["CF-Connecting-IP"].FirstOrDefault() > ?? headers["True-Client-IP"].FirstOrDefault() > ?? headers["X-Forwarded-For"].FirstOrDefault()?.Split(',')[0].Trim() > ?? headers["X-Real-IP"].FirstOrDefault() > ?? HttpContext.Connection.RemoteIpAddress?.ToString(); > > return clientIp; > } > } > ``` > **Erlang / Elixir (Phoenix / Plug)** > > ```elixir theme={null} > defmodule MyAppWeb.WhoamiController do > use MyAppWeb, :controller > import Plug.Conn > > def show(conn, _params) do > text(conn, client_ip(conn)) > end > > defp client_ip(conn) do > cond do > ip = first_header(conn, "cf-connecting-ip") -> ip > ip = first_header(conn, "true-client-ip") -> ip > ip = first_xff(conn) -> ip > ip = first_header(conn, "x-real-ip") -> ip > true -> conn.remote_ip |> :inet.ntoa() |> to_string() > end > end > > defp first_header(conn, name) do > case get_req_header(conn, name) do > [value | _] -> value > [] -> nil > end > end > > defp first_xff(conn) do > case get_req_header(conn, "x-forwarded-for") do > [value | _] -> value |> String.split(",") |> hd() |> String.trim() > [] -> nil > end > end > end > ``` ## Spoofing and trust `X-Forwarded-For` is a request header — any client can set it. Your environment ingress strips and rewrites it on the hop it controls, so for traffic arriving directly from the public internet to your service the header is trustworthy. When a CDN is in front, the CDN appends the original client IP to `X-Forwarded-For` before forwarding. The left-most entry is the real client only if every upstream hop between the client and your ingress is trusted. If you accept arbitrary `X-Forwarded-For` values from untrusted upstreams, attackers can spoof the client IP for rate-limiting, audit logs, or geo-IP checks. > [!NOTE] > > Configuration of environment-specific trusted CDN CIDR ranges is on the roadmap. Once available, you will > be able to list your CDN's published IP ranges so that `X-Real-IP` also resolves to the real client when > traffic arrives from those ranges. Until then, CDN customers should prefer `X-Forwarded-For[0]` or the > CDN's own header. ## See also * [Web service](/environment/services/web) * [Custom domain](/environment/services/custom-domain) # Create service Source: https://docs.localops.co/environment/services/create Learn how to create a new service [https://www.loom.com/embed/72b64f2f90d7498c894e7ff13b0cb219](https://www.loom.com/embed/72b64f2f90d7498c894e7ff13b0cb219) LocalOps can build a service from a source repo, a pre-built Docker image, or a Helm chart. Pick the one that matches what you already have. | You have | What LocalOps does | | - | - | | [I have code](#i-have-a-githubgitlab-repo) | Builds your repo into an image, redeploys on every push | | [I have Docker images](#i-have-docker-images) | Runs an image you already publish - no build step needed | | [I have Helm charts](#i-have-helm-charts) | Installs a public Helm chart and manages its release | ## I have a GitHub/GitLab repo To create a new service, sign in to your LocalOps account and follow these steps. 1. Navigate to the environment where you want the service to run 2. Go to "Services" tab 3. Click on "+ Add new service" tile 4. Provide service details like Name, Kind, Source repo & branch name, Dockerfile location and run command. 5. Give port, number of containers and any other details required there 6. Provide secrets necessary to run your container 7. Click "Create service" ### Source repo & branch name: If you have connected your [GitHub org/account](/accounts/connect-github) or your [GitLab group/account](/accounts/connect-gitlab), you will be able to pick a repository and its corresponding branch name here. When your devs push to this branch, a new deployment will automatically get triggered. > [!TIP] > > You can choose to turn off automatic deployments. In this case, you can only trigger deployments from within LocalOps > console. This is useful if you are deploying to a customer specific standalone environment, and if you need approvals > to deploy new changes. ### Dockerfile location You can specify the file location within your repository where we can find the Dockerfile. If the Dockerfile is present in a non-root directory, you can specify the name of the directory here. Example values - (empty) or `build` or `worker` or `app`, etc., This is optional. Default is \`\` - empty string, which means Dockerfile will be expected at the root of your git repo. This is to accommodate the case of mono-repos where you might have more than one component's codebases in the same git repo. ### ops.json location You can specify the directory within your repository where we can find the [`ops.json`](/environment/services/ops-json) file. If it sits in a non-root directory, give the name of that directory here. Example values - (empty) or `build` or `worker` or `app`, etc., This is optional. Default is \`\` - empty string, which means `ops.json` will be expected at the root of your git repo. Like the Dockerfile location, this accommodates mono-repos where more than one component's codebase lives in the same git repo and each component carries its own `ops.json`. ### Run command You can specify the run command as well. If your Dockerfile has a `CMD` directive, then that will get used by default. If you specific a different run command here in the form, it will be used instead of the `CMD` directive specified in the Dockerfile. This is also done to accomodate the case of mono-repos where you might have more than one component's codebase in the same git repo. You can have scripts of jobs/crons in the same repo. In these cases, you can use the same `Dockerfile` but a different `CMD` to run for your service. This is optional. Default is - `CMD` that is specified in your Dockerfile. #### How CMD works in Dockerfile The CMD instruction specifies the default command to run when a container is started from the Docker image. If no command is specified during the container startup (i.e., in the docker run command), this default is used. CMD can be overridden by supplying command-line arguments to docker run. CMD is useful for setting default commands and easily overridden parameters. It is often used in images as a way of defining default run parameters and can be overridden from the command line when the container is run. For example, by default, you might want a python web server to start, but also you could override this to run a node server instead: ``` CMD ["python", "-DFOREGROUND"] ``` #### Difference between CMD and ENTRYPOINT The ENTRYPOINT instruction sets the default executable for the container. Any arguments supplied to the docker run command are appended to the ENTRYPOINT command. > [!NOTE] > > Use ENTRYPOINT when you need your container to always run the same base command, and you want to allow users to append > additional commands at the end. ENTRYPOINT is particularly useful for turning a container into a standalone executable. For example, suppose you are packaging a custom script that requires arguments (e.g., “my\_script extra\_args”). In that case, you can use ENTRYPOINT to always run the script process (“my\_script”) and then allow the image users to specify the “extra\_args” on the docker run command line. You can do the following: #### Overriding CMD in LocalOps You can configure the service with custom run command `node start.js` to get a node process started instead of starting python server. ### Number of containers Specify the number of copies of your codebase / containers to run. You can define any number from 1 to 99 to support your traffic. This count is fixed. To have LocalOps vary it with load instead, see [Autoscaling](/environment/services/autoscaling). ### CPU and memory requirements for each container Define the minimum CPU and memory requirements to run each container. Service containers will be scheduled to run on the underlying compute servers as appropriate. You can also define the max CPU and max memory here. When any container crosses this limit, it will be re-booted. The minimum CPU and memory you set here are also what [autoscaling](/environment/services/autoscaling) measures against * `target_cpu` and `target_memory` are percentages of each container's minimum, so a service with no minimum set can't scale on utilization. > [!TIP] > > Specifying max CPU and max Memory is a neat trick to catch memory leaks and restart containers ### Other details You can fill out other service specific details like Port (for internal or web service), Cron schedule (for cron service), and so on. ### How to deploy Containers of the service won't start to run until you make a new deployment. Click on "Deploy" button on the top right corner to start a manual deployments. Otherwise, if you push new commits to the configured branch above, a new deployment will get triggered. Learn more at [Deploy service](/environment/services/deploy) guide. ## I have Docker images Already have a pre-built image in a registry? Pick **Docker Image** as the source while creating the service, then give the registry URL and image name - there is no Dockerfile or build step involved. See [Run Docker Images](/environment/services/docker) for the full walkthrough. ## I have Helm charts You can spin up a service from a public Helm chart - pick **Helm chart** as the source while creating the service and provide the chart details. See [Use Helm charts](/environment/services/helm-charts) for the full walkthrough. # Cron Job Source: https://docs.localops.co/environment/services/cronjob A Cron job service is like a Job service. It spins up the specific container on a given schedule. #### Run command When you [create a service](/environment/services/create), you must provide appropriate `Run command` if your Dockerfile `CMD` doesn't point at the job script. #### Cron schedule Specify a cron schedule like `5 4 * * *`. Refer to [https://crontab.guru/](https://crontab.guru/) for the syntax to specify your schedule. #### Logs You can see logs of the job via the in-built Grafana dashboard. Navigate to Monitor tab to login to Grafana dashboard. Within Grafana dashboard, filter to see `app-services` namespace logs. You can create any number of jobs in your environment. # Custom domain Source: https://docs.localops.co/environment/services/custom-domain Set a custom domain for each of your service to let users reach them using your brand's domain. Say, `app.your-awesome-site.com`. Here is how you can set it up. > [!NOTE] > > Needs the Member role in the project, or in the environment if it's > [protected](/environment/protected-environments). See > [Understanding roles](/team/understanding-roles#permissions-in-detail). ## Steps ### 1. Add your domain 1. Navigate to the specific environment dashboard (from Environments section) 2. Click on **Services** tab to see all services 3. In the Service dashboard, navigate to "Custom domain" tab. 4. Enter your new domain and click save. Clicking **"Save"** button will give you DNS records to add to your domain DNS settings. In next step, we will use these DNS records to verify the ownership of your domain and to route traffic from your domain to your environment. ### 2. Verify your domain - Add CNAME records: In this step you will verify the ownership of your domain by adding the **CNAME records** you see in above step. Go to your DNS registrar > DNS Zone and add the given CNAME records. > [!WARNING] > > After saving the DNS settings, it takes few minutes for the newly added DNS settings to propagate. Sometimes it may > also take up to 24 hours. ### 3. Deploy Once you have added the given **CNAME records** to your domain's DNS settings give it a few minutes for the DNS settings to propagate. Then, come back to Service > Custom domain settings page, and click on **"Verify and deploy"** button. > [!TIP] > > If domain verification fails then give it few more minutes for the newly updated DNS settings to propagate and try > again. If it still fails then check whether you have properly configured the given **CNAME records** in your domain's > DNS settings. LocalOps will then 1. configure your service to run on the custom domain you added and 2. auomatically provison a brand new **auto-renewing SSL Certificate** for the custom domain You can now reach your service using the new domain. ## Access current domain For your code/service to start reading the new domain, trigger a new deployment on your service. Either by pressing "Deploy" button in the service settings section. Or push a new commit on configured branch of the service. During this deployment, LocalOps fills environment variable `LOPS_SVC_HOST` with the current active domain. ``` LOPS_SVC_HOST=app.your-awesome-site.com ``` You can access this in your app (say NodeJS app) like ```js theme={null} console.log(process.env.LOPS_SVC_HOST); ``` # Running DB migrations Source: https://docs.localops.co/environment/services/db-migrations Package your database migrations as a separate image and run them as an init job or a manual job service Most applications need to apply database schema changes before the new version of the code starts serving traffic. In LocalOps, you do this in two steps: 1. Package your migration command into a **separate Dockerfile** whose `CMD` runs the migration. 2. Run that image either as an **init job** in [`ops.json`](/environment/services/ops-json#init-jobs) (automatic, on every deployment) or as a **[job service](/environment/services/job)** you trigger manually. > [!NOTE] > > Use a migration framework with versioned, linear migration files (Rails > `ActiveRecord::Migration`, Django migrations, Flyway, EF Core migrations, > etc.,). To undo a change, add a new migration instead of editing an old one. > This keeps migrations replayable across all your environments - production, > dedicated, self-hosted and PR previews. ## Step 1: Create a Dockerfile for migrations Keep the migration image in its own directory in your repo, so you can point a job at it independently of your web service. For example `migrate/Dockerfile`. The only thing that makes it a "migration image" is its `CMD` - it runs migrations and exits, instead of starting a server. **Ruby on Rails** ```docker migrate/Dockerfile theme={null} FROM ruby:3.3-slim # Postgres client libs + build tools needed by the pg gem RUN apt-get update -qq && apt-get install -y --no-install-recommends \ build-essential libpq-dev && rm -rf /var/lib/apt/lists/* WORKDIR /app # Install gems first so this layer is cached across commits COPY Gemfile Gemfile.lock ./ RUN bundle config set --local without 'development test' && bundle install COPY . . ENV RAILS_ENV=production # Run migrations and exit CMD ["bundle", "exec", "rails", "db:migrate"] ``` Rails builds `DATABASE_URL` from the environment, or you can read the individual variables in `config/database.yml`: ```yaml config/database.yml theme={null} production: adapter: postgresql encoding: unicode host: <%= ENV['DB_HOST'] %> port: <%= ENV['DB_PORT'] %> database: <%= ENV['DB_NAME'] %> username: <%= ENV['DB_USER'] %> password: <%= ENV['DB_PASS'] %> ``` > [!TIP] > > If you also seed data, use a wrapper command like `bundle exec rails db:migrate db:seed` - or keep seeding as a > second init job so you can control the order and see separate logs. **Python (Django)** ```docker migrate/Dockerfile theme={null} FROM python:3.12-slim ENV PYTHONDONTWRITEBYTECODE=1 ENV PYTHONUNBUFFERED=1 WORKDIR /app COPY requirements.txt ./ RUN pip install --no-cache-dir -r requirements.txt COPY . . # Run migrations and exit CMD ["python", "manage.py", "migrate", "--noinput"] ``` Your `settings.py` should read database credentials from environment variables, so the same image works in every environment: ```python django_app/settings.py theme={null} DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': os.environ.get('DB_NAME'), 'USER': os.environ.get('DB_USER'), 'PASSWORD': os.environ.get('DB_PASS'), 'HOST': os.environ.get('DB_HOST'), 'PORT': os.environ.get('DB_PORT'), } } ``` **Java (Flyway)** Flyway needs only your versioned SQL files, so the migration image can be small - no application jar required. ```docker migrate/Dockerfile theme={null} FROM flyway/flyway:11-alpine # Versioned migrations, eg. V1__create_tasks.sql, V2__add_index.sql COPY src/main/resources/db/migration /flyway/sql # Run migrations and exit CMD ["migrate"] ``` Flyway reads `FLYWAY_URL`, `FLYWAY_USER` and `FLYWAY_PASSWORD` from the environment. The simplest option is to add those three keys as [secrets](/environment/services/secrets) for the service - then `CMD ["migrate"]` needs no override. When the credentials come from `exports` as separate `DB_*` variables (as they do in [PR previews](/use-cases/ephemeral)), compose the JDBC URL at run time by wrapping the command in a shell: ```json ops.json theme={null} { "init": [ { "id": "migrate", "prefix": "migrate", "cmd": "sh -c 'flyway -url=jdbc:postgresql://$DB_HOST:$DB_PORT/$DB_NAME -user=$DB_USER -password=$DB_PASS migrate'", "once": true } ] } ``` > [!TIP] > > Using Spring Boot? Keep `spring.flyway.enabled=false` in your app config and let this job own migrations, so your > web containers don't each try to migrate on boot. If you prefer running Flyway through Maven or the Spring Boot jar instead of the Flyway CLI image, use a JDK base image and set `CMD ["mvn", "flyway:migrate"]` or `CMD ["java", "-jar", "app.jar", "--migrate-only"]`. **.NET (EF Core)** EF Core migrations are bundled into a self-contained executable at build time, so the runtime image needs neither the SDK nor the `dotnet-ef` tool. ```docker migrate/Dockerfile theme={null} FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build WORKDIR /src RUN dotnet tool install --global dotnet-ef ENV PATH="$PATH:/root/.dotnet/tools" COPY . . RUN dotnet restore # Produce a standalone migrations bundle RUN dotnet ef migrations bundle \ --project MyApp/MyApp.csproj \ --self-contained -r linux-x64 \ -o /src/efbundle FROM mcr.microsoft.com/dotnet/runtime:8.0 WORKDIR /app COPY --from=build /src/efbundle ./efbundle # Run migrations and exit CMD ["./efbundle"] ``` The bundle picks up the connection string the same way your app does - from `ConnectionStrings__DefaultConnection`. Add that key as a [secret](/environment/services/secrets) for the service and `CMD ["./efbundle"]` needs no override. When the credentials arrive as separate `DB_*` variables from `exports` (as they do in [PR previews](/use-cases/ephemeral)), compose the connection string at run time by wrapping the command in a shell: ```json ops.json theme={null} { "init": [ { "id": "migrate", "prefix": "migrate", "cmd": "sh -c './efbundle --connection \"Host=$DB_HOST;Port=$DB_PORT;Database=$DB_NAME;Username=$DB_USER;Password=$DB_PASS\"'", "once": true } ] } ``` > [!WARNING] > > Don't call `Database.Migrate()` on application startup. Every container would run it, they race with each other, > and a failed migration crashes your web service instead of failing the deployment cleanly. > [!NOTE] > > Commit the migration Dockerfile to the same repo as your service. Paths inside > the Dockerfile (`COPY ...`) must resolve against the build context used for > your service. Check the build logs of your first deployment if a `COPY` fails. ## Step 2A: Run migrations automatically as an init job This is the recommended option for most services. Declare the migration as an [init job](/environment/services/ops-json#init-jobs) in `ops.json`. LocalOps runs init jobs **before** your main service starts, and fails the deployment if a job fails - so a broken migration never leaves you with new code running against an old schema. See [Zero downtime deployments](#zero-downtime-deployments) below for exactly where this lands in a rollout. ```json ops.json theme={null} { "init": [ { "type": "job", "id": "migrate", "prefix": "migrate", "cmd": "bundle exec rails db:migrate", "once": true } ] } ``` ### Always set `once: true` for migrations By default, an init job runs once per copy/pod of your service. If your service runs 3 containers, your migration would run 3 times in parallel. Setting `once: true` makes the job run **exactly once across all pods** for that deployment. > [!WARNING] > > When `once` is set, `cmd` must be a fully qualified command (eg., `bundle exec > rails db:migrate`), not just arguments. LocalOps overrides the `ENTRYPOINT` in > your Dockerfile with a custom entrypoint script to get this behaviour. ### Using the dedicated migration image If you built a separate migration image and pushed it to a registry, point the init job at it with `image`: ```json ops.json theme={null} { "init": [ { "id": "migrate", "prefix": "migrate", "image": "/myapp-migrate:1.4.0", "cmd": "flyway migrate", "once": true } ] } ``` When you omit `image`, LocalOps uses the same image it just built from the latest commit in your branch/PR. That is usually what you want - the migrations are then always in lockstep with the code being deployed. ### Environment variables You don't need to repeat your database credentials in `ops.json`. Init jobs automatically receive, in this order: 1. Secrets and variables you added for the service in the LocalOps console UI 2. `exports` from cloud `dependencies` (eg., an [RDS instance](/environment/services/aws/rds)) 3. `exports` from `previews.dependencies` when running as part of a PR preview 4. Anything in the init job's own `env` block So if your [RDS dependency](/environment/services/aws/rds) exports `DB_HOST`, `DB_NAME` and friends, the migration job can read them directly. ### Migrations in PR preview environments For [ephemeral PR previews](/use-cases/ephemeral), declare an ephemeral database under `previews.dependencies` and the migration as an init job. LocalOps provisions the database first, then runs the init job - so every PR preview comes up with a freshly migrated schema. ```json ops.json theme={null} { "previews": { "dependencies": { "db": [ { "id": "db", "prefix": "db", "engine": "postgres", "version": "17.5", "exports": { "DB_HOST": "$host", "DB_PORT": "$port", "DB_USER": "$user", "DB_NAME": "$db", "DB_PASS": "$pass" } } ] } }, "init": [ { "id": "migrate", "prefix": "migrate", "cmd": "python manage.py migrate --noinput", "once": true } ] } ``` ## Step 2B: Run migrations manually as a job service Sometimes you don't want migrations tied to a deployment - for example a long-running backfill, a one-off data migration, or a production change that needs a maintenance window and an explicit human "go". In that case, create a [job service](/environment/services/job): **1. Add a new service** In your environment, go to the **Services** tab and click **+ Add new service**. Pick **Job** as the kind. **2. Point at the migration Dockerfile** Set **Dockerfile location** to the directory holding your migration Dockerfile (eg., `migrate`). See [Dockerfile location](/environment/services/create#dockerfile-location). **3. Leave the run command empty** The `CMD` in your migration Dockerfile is already the migration command, so nothing to override. If you reuse your main app's Dockerfile instead, set **Run command** to eg., `bundle exec rails db:migrate`. **4. Add secrets** Add the database [secrets](/environment/services/secrets) the migration needs. If the database is provisioned via `ops.json` dependencies, its `exports` are injected automatically. **5. Deploy to run** Click **Deploy** to run the job. The container comes up, runs migrations and shuts down. Deploy again whenever you want to re-run it. > [!TIP] > > Turn **off** automatic deployments for this service so a push to your branch > doesn't silently run a migration. Then each run is an explicit, audited action > from the LocalOps console. You can create any number of job services - eg., one for schema migrations and another for a heavy data backfill. ## Zero downtime deployments Deployments in LocalOps use Kubernetes' default rolling update strategy. When you deploy a new version, LocalOps does **not** stop your current containers first. Instead, it brings up new pods alongside the ones already serving traffic. Each new pod only starts receiving requests once it passes its [health checks](/environment/services/ops-json#health-checks), and only after the new pods are healthy and serving does Kubernetes terminate the old ones. If the new pods never become healthy, the old ones keep serving and nothing is taken away from your users. Migrations declared as init jobs run inside this rollout, in the **new** pods, before any new application container starts. The sequence for a single deployment is: 1. You push a commit (or click Deploy). LocalOps builds the new image. 2. New pods are scheduled. In each new pod, the init containers run first - this is where your migration `cmd` runs. With `once: true`, exactly one of those new pods actually performs the migration; the others wait for it to finish. 3. Once the migration exits successfully, the new pods start your application container. 4. Health checks run against the new pods. As each becomes healthy, it starts taking traffic. 5. Only then does Kubernetes terminate the old pods, which were serving the previous version the whole time. The consequence worth internalising is in steps 3 and 4: **your old containers are still serving traffic against the already-migrated schema.** There is a window - from the moment the migration commits until the last old pod is terminated - where the previous version of your code is talking to the new database schema. This is exactly why migrations need to be backward compatible with the version being replaced. > [!WARNING] > > A migration that renames or drops a column, or adds a `NOT NULL` column > without a default, will break the old pods during this window - even though > the deployment itself "succeeded". Split such changes across two deployments: > first deploy an additive, backward compatible migration (add the new column, > write to both), then in a later deployment remove what is no longer read. If a migration fails, the init container fails, the new pods never become ready, and the deployment is marked failed. Your old pods keep serving the previous version - so a bad migration costs you a failed deployment, not an outage. Do note that whatever the failed migration already committed to the database stays committed, so keep migrations small and let your framework's transaction handling do its job. ## Backfilling data A schema migration changes the shape of a table and finishes in seconds. A backfill rewrites existing rows - possibly millions of them - and can run for minutes or hours. They deserve different treatment. **Run backfills as a [job service](#step-2b-run-migrations-manually-as-a-job-service) you trigger manually, not as an init job.** An init job is the wrong home for a backfill because: * It blocks the rollout. Your deployment - and everything your team queues behind it - waits for every row to be rewritten. * It runs on every deployment. A one-time backfill would re-run on each deploy forever, until someone remembers to delete it from `ops.json`. * It couples two unrelated failures. A backfill that dies halfway fails the deployment, even though the schema change itself was fine. * You can't pace it. As a job service you decide when it runs, watch it, stop it, and run it again. ### The expand, backfill, contract sequence Keep the schema change and the data change in separate deployments, with the backfill run in between. For adding a `region` column derived from an existing `country_code`: **1. Deploy 1 - expand** An init job migration adds `region` as a **nullable** column. Your new code writes `region` on every insert and update, but still reads `country_code`. Old pods, which know nothing about `region`, keep working - the column is nullable, so their inserts are still valid. **2. Run the backfill job** Trigger the backfill job service to fill `region` for pre-existing rows. Nothing is waiting on it, so it can take as long as it needs. Re-run it until it reports zero rows remaining. **3. Deploy 2 - contract** Now that every row has a value, deploy code that reads `region`, and an init job migration that adds the `NOT NULL` constraint and drops `country_code`. Each deployment stays backward compatible with the version it replaces, which is what makes the whole sequence safe during a rolling update. See [Zero downtime deployments](#zero-downtime-deployments). ### Write backfills in batches Never rewrite a whole table in one statement - it holds locks, bloats your write-ahead log and cannot be resumed if the container is restarted. Loop over small batches instead: **Ruby on Rails** ```ruby lib/tasks/backfill.rake theme={null} namespace :backfill do task region: :environment do batch_size = Integer(ENV.fetch('BATCH_SIZE', '1000')) pause = Float(ENV.fetch('BATCH_SLEEP', '0.1')) total = 0 User.where(region: nil).in_batches(of: batch_size) do |batch| total += batch.update_all('region = country_code') Rails.logger.info("backfill:region - #{total} rows done") sleep pause end Rails.logger.info("backfill:region - complete, #{total} rows") end end ``` ```docker backfill/Dockerfile theme={null} # ... same base and dependency install as your migration image ... CMD ["bundle", "exec", "rake", "backfill:region"] ``` **Python (Django)** ```python users/management/commands/backfill_region.py theme={null} import time from django.core.management.base import BaseCommand from django.db.models import F from users.models import User class Command(BaseCommand): help = 'Backfill User.region from country_code' def add_arguments(self, parser): parser.add_argument('--batch-size', type=int, default=1000) parser.add_argument('--sleep', type=float, default=0.1) def handle(self, *args, **options): total = 0 while True: ids = list( User.objects.filter(region__isnull=True).values_list('pk', flat=True)[: options['batch_size']] ) if not ids: break total += User.objects.filter(pk__in=ids).update(region=F('country_code')) self.stdout.write(f'backfill_region: {total} rows done') time.sleep(options['sleep']) self.stdout.write(f'backfill_region: complete, {total} rows') ``` ```docker backfill/Dockerfile theme={null} # ... same base and dependency install as your migration image ... CMD ["python", "manage.py", "backfill_region", "--batch-size", "1000"] ``` Both examples share the four properties a good backfill needs: * **Idempotent** - the query selects only rows that still need work (`region IS NULL`), so a second run is cheap and a partial run is not a problem. * **Resumable** - each batch commits on its own. If the container is restarted, the next run picks up exactly where it stopped. No bookkeeping table needed. * **Throttled** - the pause between batches keeps database CPU and replication lag under control while your web service is still serving live traffic against the same database. * **Observable** - it logs progress as it goes, so you can watch it in Grafana instead of wondering whether it hung. ### Running it Create the backfill as its own [job service](#step-2b-run-migrations-manually-as-a-job-service) - separate from your schema migration job - so the two have independent logs and independent run history. Point **Dockerfile location** at `backfill`, turn **off** automatic deployments, and click **Deploy** each time you want a run. Because the job is idempotent, "resume" and "run again" are the same action. > [!TIP] > > Keep the backfill job service around after the backfill finishes. A subsequent > run is a no-op that costs one query, and it's a cheap way to confirm nothing > new slipped through while the expand deployment was live. > [!WARNING] > > A backfill runs against the same database your live service is using. Start > with a small `BATCH_SIZE` and a longer pause, watch database CPU and > replication lag on the [metrics dashboard](/environment/monitoring/metrics), > then raise the batch size if there is headroom. ## Which option should I use? | | Init job (`once: true`) | Job service | | - | - | - | | When it runs | Automatically, before every deployment | Only when you trigger a deployment for the job | | Blocks the rollout | Yes - deployment fails if the migration fails | No - independent of your web service | | Good for | Routine, fast schema migrations | Backfills, risky changes, maintenance windows | | Ordering | Guaranteed to finish before the main service starts | You control it | A common setup is both: routine migrations as an init job, plus a separate job service for occasional backfills. ## Viewing logs Migration output shows up in the built-in Grafana dashboard. Go to the **Monitor** tab of your environment to sign in to Grafana, and filter logs for the `app-services` namespace. See [Logs](/environment/monitoring/logs) for more. Grafana collects output from every container, including init jobs and job services, so it is the place to read a migration's own output. To watch what happens next - whether your service actually starts against the new schema - the [LocalOps CLI](/cli/install-macos) streams the running service straight to your terminal: ```sh theme={null} ops logs --env staging --svc web ``` ## Good practices * **Make migrations backward compatible.** During a rollout, old and new containers run side by side for a short while. Add columns as nullable, backfill separately, and only drop columns in a later deployment. See [Zero downtime deployments](#zero-downtime-deployments). * **Keep migrations fast.** Init jobs block the deployment. Move long backfills to a separate job service - see [Backfilling data](#backfilling-data). * **Make them idempotent and re-runnable.** Init jobs run on every deployment, so a no-op second run must be safe. Most migration frameworks handle this with a schema-version table. * **Avoid running migrations from your app's entrypoint.** Doing so runs them once per container, races between copies, and slows down every restart. Use `once: true` init jobs instead. * **Don't mix DDL and long transactions.** Some databases take heavy locks; prefer separate, small migrations. # Delete service Source: https://docs.localops.co/environment/services/delete When you delete a service, all containers belonging to the service will stop. > [!NOTE] > > Needs the Member role in the project, or in the environment if it's > [protected](/environment/protected-environments). See > [Understanding roles](/team/understanding-roles#permissions-in-detail). To proceed, follow the steps below: 1. Navigate to the correct environment 2. Click on "Services" and navigate to the correct service 3. Go to "Settings" section of the service 4. Click on "Delete" button and confirm your action. 5. Deletion will start and complete in 0-2 mins. If the service is deleted before its first deployment, it will be deleted immediately without any logs. If the service was running within the environment, it will take a few mins to complete the deletion. You can follow the activity in Ops section. # Deploy a service Source: https://docs.localops.co/environment/services/deploy Deployment can be started for a service either manually from LocalOps console or by pushing new code to the configured service repo and branch name. ## Automatic deployments How a deployment gets triggered depends on what the service was created from - a source repo, a Docker image, or a Helm chart. ### GitHub/GitLab repos Whenever your team pushes new code to Git repository, LocalOps can automatically pull the hcanges, build them as Docker images very quickly and deploy seamlessly on the corresponding environment. If you have a local development environment for the git repository configured for the given service, you can simply follow these steps to start deployment. ```sh theme={null} $ git checkout $ ..add commits $ git push ``` If your GitHub organization doesn't allow direct git push on the branch, you can ask your team to raise pull requests (PRs) targeting the configured branch name of the service. If you merge the PR, a new deployment will start in LocalOps with the latest commit on that branch. Or if you directly edit files in Github website and make new commits on the configured branch name of the service, a new deployment will start. A new build & deployment process will start in either of these cases. Navigate to "Deployments" tab within the same service section to see the logs. > [!NOTE] > > For commits to get automatically deployed, the github user who made the commits, must be added to your LocalOps > account as a user. And they must have linked their Github profile with LocalOps from inside Profile settings: > [https://console.localops.co/profile](https://console.localops.co/profile) ### Docker images A service created from a [Docker image](/environment/services/docker) has no repo to watch, so there is no push event to react to. Trigger the deployment from wherever you publish the image - typically the last step of the pipeline that pushed the new tag - by calling the [Deploy Service](/api-reference/deployments/deploy-service) endpoint with the tag you just published: ```sh theme={null} curl -X POST https://sdk.localops.co/v1/environments//services//deploy \ -H "Authorization: Bearer $LOCALOPS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"docker_image_tag": "1.4.2"}' ``` From CI, run that call as the step right after your image push: **GitHub Actions** Use our [deploy action](https://github.com/localopsco/deploy-action) rather than calling the endpoint by hand: ```yaml theme={null} - name: Trigger LocalOps Deployment uses: localopsco/deploy-action@v0 with: api_token: ${{ secrets.LOCALOPS_API_TOKEN }} environment_id: 'f0fc03c6-0698-49f4-a05d-380c46091df1' service_id: '0cd0179a-fb84-45c7-ac85-f51aac92599d' docker_image_tag: ${{ github.sha }} ``` Store the token as an encrypted secret. Pass exactly one of `commit_id`, `docker_image_tag` or `helm_chart_version` - whichever matches how the service was created. **GitLab CI** ```yaml theme={null} deploy: stage: deploy image: curlimages/curl:latest variables: TAG: $CI_COMMIT_SHA script: - | curl -fsS -X POST \ "https://sdk.localops.co/v1/environments/$LOCALOPS_ENV_ID/services/$LOCALOPS_SERVICE_ID/deploy" \ -H "Authorization: Bearer $LOCALOPS_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"docker_image_tag\": \"$TAG\"}" ``` Add `LOCALOPS_API_KEY`, `LOCALOPS_ENV_ID` and `LOCALOPS_SERVICE_ID` under **Settings > CI/CD > Variables**, and mask the API key. > [!TIP] > > Tag images with something immutable - the commit SHA works well - so each deployment points at exactly one build. ### Helm charts A service created from a [Helm chart](/environment/services/helm-charts) works the same way, with the chart version in place of the image tag: ```sh theme={null} curl -X POST https://sdk.localops.co/v1/environments//services//deploy \ -H "Authorization: Bearer $LOCALOPS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"helm_chart_version": "2.1.0"}' ``` Call it from the job that publishes the chart, so a newly pushed chart version rolls out without anyone opening the console. **GitHub Actions** ```yaml theme={null} - name: Trigger LocalOps Deployment uses: localopsco/deploy-action@v0 with: api_token: ${{ secrets.LOCALOPS_API_TOKEN }} environment_id: 'f0fc03c6-0698-49f4-a05d-380c46091df1' service_id: '0cd0179a-fb84-45c7-ac85-f51aac92599d' helm_chart_version: '2.1.0' ``` **GitLab CI** ```yaml theme={null} deploy: stage: deploy image: curlimages/curl:latest script: - | curl -fsS -X POST \ "https://sdk.localops.co/v1/environments/$LOCALOPS_ENV_ID/services/$LOCALOPS_SERVICE_ID/deploy" \ -H "Authorization: Bearer $LOCALOPS_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"helm_chart_version\": \"$CHART_VERSION\"}" ``` > [!NOTE] > > All three shapes are the same endpoint - it takes `commit_id`, `docker_image_tag` or `helm_chart_version` depending > on how the service was created. See the [Deploy Service](/api-reference/deployments/deploy-service) reference for the > full request and response schema. ## Manual deployment 1. Click on "environments" on the left 2. Navigate into the relevant environment 3. Navigate to Services tab 4. Click on the service where you want to trigger new deployment 5. On the top right corner, click on "Deploy". 6. Verify the details on the confirmation window - the commit for a repo-based service, the image tag for a [Docker image](/environment/services/docker) service, or the chart version for a [Helm chart](/environment/services/helm-charts) service 7. Click on "Confirm" to proceed. A new deployment will start. Navigate to "Deployments" tab within the same services section to see the logs. # Run Docker Images Source: https://docs.localops.co/environment/services/docker You now spin up a service using any pre-built public docker image. While creating a new service, just pick Docker Image as source and provide 1. Docker registry url 2. Docker image name And trigger a new manual deployment anytime. You can pick a specific version to run, while triggering new deployment. Default version/tag would be `latest`. All options supported in a traditional service are supported in Docker image services also. So you can: 1. Run it as `web`, `worker`, `internal` service, `job` or `cron`. 2. Configure environment variables and secrets 3. Specific resource requirements like CPU and Memory 4. Run any number of copies of the container to scale it based on load 5. Attach custom domain if the service is of type `web`. # Use Helm charts Source: https://docs.localops.co/environment/services/helm-charts You can spin up a new service using any public Helm Chart. While creating a new service, just pick "Helm chart" as the Source and provide 1. Helm repo url 2. Helm chart name 3. Values.yaml And trigger a new deployment. While triggering a new deployment, provide the specific version to run. You can edit your current service in Service > Settings section and update Helm Values to customise your deployment. ### Interacting with the chart and its internal services: Say you want to run Postgresql as a service using its Helm chart. #### Case 1: Other services to use chart's services Say you want your NodeJS app to use Postgres as its database. The other service (NodeJS service) from the same environment can use Postgresql database running as part of the Helm Chart installation. Using "service alias" of the helm chart, one can frame the hostname for the chart's service (postgresql) using the format below. ``` $chart_svc_alias/service/ ``` And this can be given as value in any Secret added in secret section. Your code can use it as `hostname` for the corresponding service. `` is the name of the service that is running as part of Helm chart installation and is of type `NodePort` or `ClusterIP`. Refer to your Helm chart's documentation to find the ``. For our current example: You can add this as DB\_HOST secret under secrets section of the NodeJS app service and use it in your code via env var. ``` $chart_svc_alias/service/postgresql ``` #### Case 2: Charts to use another chart's services Say you want to use Temporal and want it to use Postgres as its database. A Helm chart running within the same environment as a service, can use services running as part of another helm chart by using their service alias as an alias for hostname. And provide them as below in Values.yaml configuration. ```yaml theme={null} database: host: { { hosts "$other_chart_svc_alias/service/" } } ``` Any Values.Yaml configuration can have go-template style expressions wrapped in `{{` and `}}`. `hosts` here is a helper function we support today that can bring the internal dns hostname of any service running within the same LocalOps environment. For current example, run Temporal chart and Postgres chart as services within your LocalOps environemnt. And provide the following in Temporal chart's values.yaml configuration. ```yaml theme={null} default: driver: sql sql: driverName: postgres host: {{ hosts "$pg_chart_svc_alias/service/postgresql" }} port: 5432 ``` # How to instrument Source: https://docs.localops.co/environment/services/instrument-service Expose custom metrics from your services to the inbuilt Prometheus + Grafana stack so they appear automatically in your environment's dashboards. This is a guide to learn more about how you can instrument your services by exposing custom metrics that are crucial for your app/use case. For example, you can record `emails_received`, `emails_sent`, `emails_bounced` if you're building a transaction email service. Or you can record `tcp_connections` if you're building realtime services. ## How to instrument your services LocalOps by default embeds Prometheus in every environment. To make your service's metrics available to Prometheus, follow these steps to expose an endpoint that responds with metrics in the format Prometheus expects. ### 1. Use a Prometheus client library in code You can do this without a Prometheus client library too, but it is much easier if you use the library. Prometheus officially supports client libraries for these languages: 1. Go 2. Java 3. Python 4. Rust 5. Erlang 6. NodeJS There are unofficial community-maintained libraries for other languages too. Check [https://prometheus.io/docs/instrumenting/clientlibs/](https://prometheus.io/docs/instrumenting/clientlibs/) for the full list. Please follow the corresponding language guide on how to make custom metrics available. ### 2. Expose an endpoint in your service like `/metrics` Define a specific endpoint like `/metrics` in your service and connect the Prometheus client library's URL handler to it. This endpoint will be called by the inbuilt monitoring stack (Prometheus) periodically to scrape the metrics exposed in step 1. ### 3. Declare the metrics endpoint in `ops.json` `ops.json` lets you define configuration specific to your service. Just declare a `metrics` key like below in `ops.json`: ```json theme={null} { "metrics": { "endpoint": "/metrics", "interval": 15, "port": 9090 } } ``` `interval` is how often Prometheus will hit this endpoint, in seconds. Please don't keep it too low (like 1 second). Your service might get too busy handling these requests instead of handling real user requests. LocalOps will then make these metrics available automatically in the Grafana dashboard via Prometheus, just like any other metric. ## Language-specific guides End-to-end examples (dependency install, sample code, `ops.json`, and recommended community Grafana dashboard IDs) are available for each runtime: * [Java](/environment/services/instrument/java) * [Python](/environment/services/instrument/python) * [Node.js](/environment/services/instrument/nodejs) * [Go](/environment/services/instrument/golang) * [.NET](/environment/services/instrument/dotnet) * [Erlang](/environment/services/instrument/erlang) > [!NOTE] > > For Helm charts, the same instrumentation can be included in the charts you generate and publish. If a Prometheus + Grafana stack is installed and configured in any target Kubernetes cluster where your Helm chart is deployed, it will automatically collect and visualize the same metrics in Grafana. # .NET Source: https://docs.localops.co/environment/services/instrument/dotnet Expose .NET runtime and custom Prometheus metrics from a .NET service running on LocalOps, and visualize them with a community Grafana dashboard. A complete walkthrough of instrumenting a .NET service using [`prometheus-net`](https://github.com/prometheus-net/prometheus-net), the most widely adopted .NET Prometheus client. See the [overview](/environment/services/instrument-service) for the general approach. ## 1. Add the dependency ```bash theme={null} dotnet add package prometheus-net dotnet add package prometheus-net.AspNetCore ``` ## 2. Register custom metrics and expose `/metrics` `prometheus-net` automatically registers .NET runtime metrics (GC, JIT, thread pool, exceptions) and process metrics. `KestrelMetricServer` starts a standalone metrics endpoint on a dedicated port. ```csharp theme={null} using Prometheus; var emailsSent = Metrics.CreateCounter( "emails_sent_total", "Total number of emails sent", new CounterConfiguration { LabelNames = new[] { "status" }, }); var server = new KestrelMetricServer(port: 9090); server.Start(); emailsSent.WithLabels("success").Inc(); // Keep the process alive (e.g., in a console app) await Task.Delay(Timeout.Infinite); ``` > [!TIP] > > If you're already running ASP.NET Core, use `app.UseMetricServer()` and `app.UseHttpMetrics()` to expose `/metrics` > on your main app port — `UseHttpMetrics` also automatically tracks HTTP request durations, status codes, and route > labels. Just point `ops.json` at your main app port. ## 3. Declare the metrics endpoint in `ops.json` ```json theme={null} { "metrics": { "endpoint": "/metrics", "interval": 15, "port": 9090 } } ``` ## 4. Visualize with a community dashboard | Dashboard | ID | Notes | | - | - | - | | [prometheus-net](https://grafana.com/grafana/dashboards/10427) | `10427` | Pre-built dashboard for the default metrics exposed by `prometheus-net` / `Prometheus.AspNetCore`. | | [ASP.NET Core - controller summary (Prometheus)](https://grafana.com/grafana/dashboards/10915) | `10915` | Visualizes ASP.NET Core HTTP metrics provided by the `prometheus-net` middleware (per-controller request rates, durations). | | [Dotnet Runtime Metrics](https://grafana.com/grafana/dashboards/23179) | `23179` | .NET runtime metrics dashboard supporting both .NET 9+ built-in metrics and `OpenTelemetry.Instrumentation.Runtime`. | To import: in Grafana, go to **Dashboards → New → Import**, enter the dashboard ID, and select your LocalOps Prometheus data source. You'll instantly see GC heap usage, JIT activity, thread pool stats, exception rates, and HTTP request throughput. Your custom application metrics (`emails_sent_total`, etc.) can be charted alongside. # Erlang Source: https://docs.localops.co/environment/services/instrument/erlang Expose BEAM VM and custom Prometheus metrics from an Erlang service running on LocalOps, and visualize them with a community Grafana dashboard. A complete walkthrough of instrumenting an Erlang service using [`prometheus.erl`](https://github.com/prometheus-erl/prometheus.erl) plus [`prometheus_httpd`](https://github.com/prometheus-erl/prometheus_httpd) for the metrics endpoint. See the [overview](/environment/services/instrument-service) for the general approach. ## 1. Add the dependencies In `rebar.config`: ```erlang theme={null} {deps, [ {prometheus, "4.11.0"}, {prometheus_httpd, "2.1.11"} ]}. ``` ## 2. Register custom metrics and expose `/metrics` `prometheus_httpd:start/1` exposes `/metrics` and, with default collectors enabled, includes BEAM VM metrics (memory, schedulers, processes, atom table, ETS, ports). ```erlang theme={null} -module(metrics_app). -export([start/0]). start() -> ok = application:ensure_started(prometheus), ok = application:ensure_started(prometheus_httpd), prometheus_counter:declare([ {name, emails_sent_total}, {help, "Total number of emails sent"}, {labels, [status]} ]), prometheus_httpd:start([{port, 9090}]), prometheus_counter:inc(emails_sent_total, [success]). ``` > [!TIP] > > For Elixir applications, use [`PromEx`](https://github.com/akoutmos/prom_ex) instead — it bundles BEAM, Phoenix, Ecto, > Oban, and Plug instrumentation with pre-built Grafana dashboards you can import as part of its setup. ## 3. Declare the metrics endpoint in `ops.json` ```json theme={null} { "metrics": { "endpoint": "/metrics", "interval": 15, "port": 9090 } } ``` ## 4. Visualize with a community dashboard | Dashboard | ID | Notes | | - | - | - | | [Erlang-Memory-Allocators](https://grafana.com/grafana/dashboards/18694) | `18694` | BEAM memory allocator breakdown. | | [Erlang-Distribution](https://grafana.com/grafana/dashboards/17907) | `17907` | Erlang distribution (inter-node) traffic metrics. | The canonical collection of BEAM dashboards is the [`prometheus-erl/beam-dashboards`](https://github.com/prometheus-erl/beam-dashboards) repository — it contains JSON dashboards covering memory, schedulers, processes, ETS, and more, that you can import directly into Grafana. To import: in Grafana, go to **Dashboards → New → Import**, enter the dashboard ID (or upload the JSON), and select your LocalOps Prometheus data source. You'll see scheduler utilization, run queues, memory by allocator type, process counts, and ETS table stats. Your custom application metrics (`emails_sent_total`, etc.) can be charted alongside. > [!TIP] > > The Erlang-Distribution dashboard is most useful when your nodes are actually clustered. See > [BEAM clustering](/environment/services/beam-clustering) for how to cluster your Elixir/Erlang services with a single > `ops.json` key. # Golang Source: https://docs.localops.co/environment/services/instrument/golang Expose Go runtime, process, and custom Prometheus metrics from a Go service running on LocalOps, and visualize them with a community Grafana dashboard. A complete walkthrough of instrumenting a Go service using the official [`client_golang`](https://github.com/prometheus/client_golang) library. See the [overview](/environment/services/instrument-service) for the general approach. ## 1. Add the dependency ```bash theme={null} go get github.com/prometheus/client_golang/prometheus go get github.com/prometheus/client_golang/prometheus/promauto go get github.com/prometheus/client_golang/prometheus/promhttp ``` ## 2. Register custom metrics and expose `/metrics` The default registry automatically exports Go runtime metrics (`go_*` — goroutines, GC pauses, heap, etc.) and process metrics (`process_*` — CPU, memory, open FDs). ```go theme={null} package main import ( "net/http" "github.com/prometheus/client_golang/prometheus" "github.com/prometheus/client_golang/prometheus/promauto" "github.com/prometheus/client_golang/prometheus/promhttp" ) var emailsSent = promauto.NewCounterVec( prometheus.CounterOpts{ Name: "emails_sent_total", Help: "Total number of emails sent", }, []string{"status"}, ) func main() { emailsSent.WithLabelValues("success").Inc() http.Handle("/metrics", promhttp.Handler()) http.ListenAndServe(":9090", nil) } ``` > [!TIP] > > If your service already serves HTTP on another port, you can mount `promhttp.Handler()` on your existing mux at > `/metrics` instead of starting a separate listener. Just point `ops.json`'s `port` at your main app port. ## 3. Declare the metrics endpoint in `ops.json` ```json theme={null} { "metrics": { "endpoint": "/metrics", "interval": 15, "port": 9090 } } ``` ## 4. Visualize with a community dashboard | Dashboard | ID | Notes | | - | - | - | | [Go Runtime Metrics](https://grafana.com/grafana/dashboards/14061) | `14061` | Built by Grafana Labs specifically for the Prometheus Go Client Library — recommended starting point. | | [Go Processes](https://grafana.com/grafana/dashboards/6671) | `6671` | Long-running community dashboard. Memory used, file descriptors, GC details, per-process status. | | [Go Metrics](https://grafana.com/grafana/dashboards/10826) | `10826` | Kubernetes-oriented Go runtime dashboard, useful if you deploy via Helm. | To import: in Grafana, go to **Dashboards → New → Import**, enter the dashboard ID, and select your LocalOps Prometheus data source. You'll instantly see goroutine counts, GC pause times, heap allocations, and CPU usage. Your custom application metrics (`emails_sent_total`, etc.) can be charted alongside. # Java Source: https://docs.localops.co/environment/services/instrument/java Expose JVM and custom Prometheus metrics from a Java service running on LocalOps, and visualize them with a community Grafana dashboard. A complete walkthrough of instrumenting a Java service using the official [Prometheus Java client library](https://prometheus.github.io/client_java/) (`client_java` v1.x). See the [overview](/environment/services/instrument-service) for the general approach. ## 1. Add the Prometheus client dependency Add these dependencies to your `pom.xml` (Maven): ```xml theme={null} io.prometheus prometheus-metrics-core 1.3.6 io.prometheus prometheus-metrics-instrumentation-jvm 1.3.6 io.prometheus prometheus-metrics-exporter-httpserver 1.3.6 ``` Or with Gradle (`build.gradle`): ```groovy theme={null} implementation 'io.prometheus:prometheus-metrics-core:1.3.6' implementation 'io.prometheus:prometheus-metrics-instrumentation-jvm:1.3.6' implementation 'io.prometheus:prometheus-metrics-exporter-httpserver:1.3.6' ``` ## 2. Register custom metrics and expose `/metrics` Register default JVM metrics, define your own custom counters/gauges, and start an HTTP server that exposes them on `/metrics`: ```java theme={null} import io.prometheus.metrics.core.metrics.Counter; import io.prometheus.metrics.exporter.httpserver.HTTPServer; import io.prometheus.metrics.instrumentation.jvm.JvmMetrics; public class App { static final Counter emailsSent = Counter.builder() .name("emails_sent_total") .help("Total number of emails sent") .labelNames("status") .register(); public static void main(String[] args) throws Exception { // Register out-of-the-box JVM metrics (memory, GC, threads, classloader, etc.) JvmMetrics.builder().register(); // Start the metrics HTTP server on port 9090 HTTPServer.builder() .port(9090) .buildAndStart(); // Increment your custom metric anywhere in your code emailsSent.labelValues("success").inc(); } } ``` This starts a separate HTTP server on port `9090` that responds to `GET /metrics` in Prometheus exposition format — including JVM metrics like `jvm_memory_used_bytes`, `jvm_gc_pause_seconds`, `jvm_threads_live_threads`, plus your custom `emails_sent_total`. > [!TIP] > > If you're using Spring Boot, the typical approach is Spring Boot Actuator + Micrometer's Prometheus registry. Add > `io.micrometer:micrometer-registry-prometheus` and set `management.endpoints.web.exposure.include=prometheus` in > `application.properties`. The `/actuator/prometheus` endpoint is then exposed on your main service port. ## 3. Declare the metrics endpoint in `ops.json` ```json theme={null} { "metrics": { "endpoint": "/metrics", "interval": 15, "port": 9090 } } ``` Prometheus will now scrape `http://:9090/metrics` every 15 seconds and make every metric — JVM and custom — available in Grafana. ## 4. Visualize JVM metrics with a community dashboard Instead of building JVM dashboards from scratch, import a battle-tested community dashboard from [grafana.com/grafana/dashboards](https://grafana.com/grafana/dashboards). | Dashboard | ID | Notes | | - | - | - | | [JVM (Micrometer)](https://grafana.com/grafana/dashboards/4701) | `4701` | Most popular JVM dashboard. Built for Micrometer but most panels work with `client_java` v1.x since metric names like `jvm_memory_used_bytes` and `jvm_threads_live_threads` overlap. | | [JVM (Micrometer) — alternative](https://grafana.com/grafana/dashboards/8898) | `8898` | Alternative JVM dashboard, also Micrometer-based. | | [JVM SpringBoot3](https://grafana.com/grafana/dashboards/22108) | `22108` | For Spring Boot 3.x apps using Actuator + Micrometer. | To import: in Grafana, go to **Dashboards → New → Import**, enter the dashboard ID, and select your LocalOps Prometheus data source. You'll instantly see heap/non-heap memory, GC activity, thread counts, classloader stats, and more. Your custom application metrics (`emails_sent_total`, etc.) can be charted alongside in the same or a separate dashboard. # Node.js Source: https://docs.localops.co/environment/services/instrument/nodejs Expose Node.js runtime and custom Prometheus metrics from a Node.js service running on LocalOps, and visualize them with a community Grafana dashboard. A complete walkthrough of instrumenting a Node.js service using the popular [`prom-client`](https://github.com/siimon/prom-client) library. See the [overview](/environment/services/instrument-service) for the general approach. ## 1. Add the dependency ```bash theme={null} npm install prom-client ``` ## 2. Register custom metrics and expose `/metrics` `collectDefaultMetrics` enables Node.js runtime metrics (event loop lag, heap size, GC duration, active handles, etc.). ```javascript theme={null} const http = require('http'); const client = require('prom-client'); const register = new client.Registry(); client.collectDefaultMetrics({ register }); const emailsSent = new client.Counter({ name: 'emails_sent_total', help: 'Total number of emails sent', labelNames: ['status'], registers: [register], }); http.createServer(async (req, res) => { if (req.url === '/metrics') { res.setHeader('Content-Type', register.contentType); res.end(await register.metrics()); return; } res.statusCode = 404; res.end(); }).listen(9090); emailsSent.labels('success').inc(); ``` > [!TIP] > > For Express apps, you can mount the metrics handler directly on your main app port using > [`express-prom-bundle`](https://github.com/jochen-schweizer/express-prom-bundle) — it also automatically tracks HTTP > request durations, status codes, and route labels. ## 3. Declare the metrics endpoint in `ops.json` ```json theme={null} { "metrics": { "endpoint": "/metrics", "interval": 15, "port": 9090 } } ``` ## 4. Visualize with a community dashboard | Dashboard | ID | Notes | | - | - | - | | [NodeJS Application Dashboard](https://grafana.com/grafana/dashboards/11159) | `11159` | The most widely used dashboard for `prom-client` — event loop lag, heap, GC, handles, HTTP request rate. | | [NodeJS Applications Dashboard](https://grafana.com/grafana/dashboards/19062) | `19062` | Modern alternative requiring Grafana >= 10.0, supports the full set of `prom-client` default metrics. | | [NodeJS Applications and Logs Dashboard](https://grafana.com/grafana/dashboards/20371) | `20371` | Combines `prom-client` metrics with Loki logs for unified observability. | To import: in Grafana, go to **Dashboards → New → Import**, enter the dashboard ID, and select your LocalOps Prometheus data source. You'll instantly see heap usage, event loop lag, GC pauses, active handles, and more. Your custom application metrics (`emails_sent_total`, etc.) can be charted alongside. # Python Source: https://docs.localops.co/environment/services/instrument/python Expose process, runtime, and custom Prometheus metrics from a Python service running on LocalOps, and visualize them with a community Grafana dashboard. A complete walkthrough of instrumenting a Python service using the official [`prometheus_client`](https://github.com/prometheus/client_python) library. See the [overview](/environment/services/instrument-service) for the general approach. ## 1. Add the dependency ```bash theme={null} pip install prometheus-client ``` Or in `requirements.txt`: ``` prometheus-client>=0.20.0 ``` ## 2. Register custom metrics and expose `/metrics` `start_http_server` spins up a dedicated HTTP server on the given port that serves `/metrics`. The default registry already includes process metrics (CPU, memory, open FDs) and Python runtime metrics (GC stats, threads). ```python theme={null} import time from prometheus_client import Counter, start_http_server emails_sent = Counter( 'emails_sent_total', 'Total number of emails sent', ['status'], ) if __name__ == '__main__': start_http_server(9090) while True: emails_sent.labels(status='success').inc() time.sleep(1) ``` > [!TIP] > > For ASGI apps (FastAPI, Starlette), use [`prometheus-fastapi-instrumentator`](https://github.com/trallnag/prometheus-fastapi-instrumentator) > to mount `/metrics` on your main app port. For Django, use [`django-prometheus`](https://github.com/korfuri/django-prometheus). > For Flask, use [`prometheus-flask-exporter`](https://github.com/rycus86/prometheus_flask_exporter). ## 3. Declare the metrics endpoint in `ops.json` ```json theme={null} { "metrics": { "endpoint": "/metrics", "interval": 15, "port": 9090 } } ``` ## 4. Visualize with a community dashboard Python doesn't have a single canonical community dashboard like JVM or Node.js, but the metrics exposed by the default registry (`process_*` and `python_*`) are well-supported by generic process dashboards. | Dashboard | ID | Notes | | - | - | - | | [Prometheus Stats](https://grafana.com/grafana/dashboards/2) | `2` | Generic dashboard for `process_*` metrics (CPU, memory, FDs) that work for any Python service using `prometheus_client`. | | [Node Exporter Full](https://grafana.com/grafana/dashboards/1860) | `1860` | Host-level metrics if you also want OS-level context for your Python service. | For a Python-app-specific dashboard with panels for requests/sec, latency percentiles, error rates, app uptime, and interpreter version, see [pilosus/prometheus-client-python-app-grafana-dashboard](https://github.com/pilosus/prometheus-client-python-app-grafana-dashboard) on GitHub — it's a JSON dashboard you can import directly. You can also browse [grafana.com/grafana/dashboards](https://grafana.com/grafana/dashboards/?search=python) for more Python-related community dashboards. To import: in Grafana, go to **Dashboards → New → Import**, enter the dashboard ID (or upload the JSON), and select your LocalOps Prometheus data source. # Internal service Source: https://docs.localops.co/environment/services/internal An Internal service is a lot like Web service, but it is not exposed to public internet. It is available to get used from within the environment by other services. #### Port When you [create a service](/environment/services/create), you must provide `port` number where your Dockerfile exposes the running code. #### Reach it from your machine Because an internal service has no public URL, you cannot open it in a browser or point a local tool at it. Forward its port to your machine instead: ```sh theme={null} ops proxy --env staging --svc ``` That binds the same port locally that the service listens on, so `http://localhost:` reaches it for as long as the command runs. See [CLI usage](/cli/usage#forward-a-service-port-to-localhost) for the full set of options. #### Number of replicas For redundancy, ensure you set at least 2 as the number of replicas. This is a best practice yet you can enter 1 if it better suits your use case. This is a fixed count. To vary it with load instead, see [Autoscaling](/environment/services/autoscaling). #### No downtime deployments All deployments are no-downtime deployments. When LocalOps deploys your code, it brings up new containers with new code first. If they become healthy, old containers will be stopped. #### Logs You can see logs of running containers via the in-built Grafana dashboard. Navigate to Monitor tab to login to Grafana dashboard. Within Grafana dashboard, filter to see `app-services` namespace logs. To watch one service as it runs, `ops logs --env staging --svc ` streams the same output to your terminal. See [CLI usage](/cli/usage#stream-logs-from-a-service). You can create any number of internal services to suit your application architecture. All of the above will be applicable for each of them. # Job Source: https://docs.localops.co/environment/services/job A job service is a one off container that comes up to run a specific logic once and shuts down. When you [create a service](/environment/services/create), you must provide appropriate `Run command` if your Dockerfile `CMD` doesn't point at the job script. #### Logs You can see logs of the job via the in-built Grafana dashboard. Navigate to Monitor tab to login to Grafana dashboard. Within Grafana dashboard, filter to see `app-services` namespace logs. You can create any number of jobs in your environment. # Deploying Micro Services Source: https://docs.localops.co/environment/services/micro-services Your application may be composed of smaller micro services that depend on each other to fulfill business logic. This guide will explain how to deploy your micro-services and make them accessible to each other within the environment. You can login to LocalOps and create any number of environments and any number of services within an app environment. Services can be of type - `Web/External service` or `Internal service` to expose themselves for either public usage (`External`) or private usage within your environment (`Internal`). ### Using Service Alias as Hostname When you [create a service](/environment/services/create), say `service1`, you will get an unique label called `Alias`. You can find this in "Overview" tab of `service1`. ![](https://mintcdn.com/localops/RWcRMH72tArZ7dWg/environment/services/images/svc-alias.png?fit=max\&auto=format\&n=RWcRMH72tArZ7dWg\&q=85\&s=0deccc2dd50018b2da1278331f0c4d53) You can copy this alias string as-is from `service1` and use it in other dependent service, say `service2` as secret variable to represent `service1` host name. Within your code, you can access this as usual as an environment variable to denote service1's host name. ![](https://mintcdn.com/localops/RWcRMH72tArZ7dWg/environment/services/images/micro-services.png?fit=max\&auto=format\&n=RWcRMH72tArZ7dWg\&q=85\&s=5ead98ac0ef2b236c59844476ddbce56) Service `Alias` acts as an alias for a specific service's internal/private DNS hostname. It is unique within an environment and will not change during the lifetime of a service. You can pass the alias string as a secret variable to another service within the environment. At run time, when the secret is passed as environment variable to service using the alias, the alias string will be replaced with actual internal host name of the service. # ops.json magic Source: https://docs.localops.co/environment/services/ops-json Define health checks, configure ingress, cloud resources and more with a simple JSON file ## Overview The `ops.json` file allows you to declaratively define configuration for your services. Using service configuration `ops.json`, you can spin up * Init jobs (Seed dbs, run migrations, etc) * Crons * Health checks * Cloud dependencies like S3, RDS, SQS queue, etc * Volumes - scratch space, durable disks and secret files * Sidecar containers * and more.. ## How it Works 1. Add an `ops.json` file to your Github repository 2. Declare configuration for your service in `ops.json` 3. Commit and push to your repo. LocalOps will trigger a deployment while honoring `ops.json` configuration. ## Order of operations run from `ops.json` Here is the order in which resources/declarations defined in ops.json are provisioned during a deployment: 1. Dependencies defined in `dependencies` are provisioned first. [See here](/environment/services/ops-json#automatic-provisioning-of-cloud-resources) 2. Dependencies defined in `previews.dependencies` are provisioned in the order defined. [See here](/environment/services/ops-json#ephemeral-databases-and-services-for-pull-request-previews) 3. Jobs defined in `init` array are executed in order. These jobs must start and finish one after the other successfully. [See here](/environment/services/ops-json#init-jobs) 4. Main service is run. 5. Cron jobs defined in `cron` are started. [See here](/environment/services/ops-json#configuring-cron-service) 6. Workers in `previews.workers` are started. [See here](/environment/services/ops-json#isolated-workers) > [!NOTE] > > Note: #2 and #3 are applicable and run in Pull request preview sevices ## Init Jobs Let's say you want to run a db migration before a service is started or wait for another service is started before starting the current service. You can use init to configure them like below: ```json theme={null} { "init": [ { "type": "job", "id": "migrate", "prefix": "migrate", "cmd": "python3 manage.py migrate", "env": { "var": "value" } }, { "type": "service", "id": "wait_for_service", "prefix": "service_wait", "service": "$svc-123", "health": { "path": "/health", "status": 200 } } ] } ``` Init has two types of configuration: 1. `job` - Executes a command on every pod startup using the specified Docker image 2. `service` - Waits for a dependent service to become available before starting. ### Common Parameters * `type` - Type of init either `job` or `service`, defaults to `job` when not specified * `id` - Unique identifier to identify this resource within the environment * `prefix` - String that will be used as prefix in the name of the resource ### Configuration for `init` job: * `image` - Image name with tag/version. Eg., `nginx:1.29`. This is optional. If the `image` is not provided, we use the same image that was used to run your original service, which was built with the latest commit in your branch/PR. * `cmd` - start command. Used on the `image` you provide in this config or the image LocalOps built using latest commit in your branch/PR. * `env` - Pass any environment variable necessary to run this image. In addition, when you don't provide an `image` in this config, the image LocalOps built using latest commit in the PR will be used and all the secrets you added for this service in LocalOps console UI will also be injected into the job. #### Run the job once accross all the pods Let's say you want to run migration for your DB or seed your data, By default all the job mentioned in the init container will be run once per every copy/pod that is created. To control the behaviour for your job to run once across all pods, you can set the `once` parameter to `true`. > [!NOTE] > > When `once` is set, the `cmd` must be a fully qualified command not just arguments. By default kubernetes or helm > doesn't support this, we override your entrypoint(if exists) in your Dockerfile with a custom entrypoint script to get > the desired behaviour. ### Configuration for `service` job: * `name` - alias for the service * `health` - optional health configuration. by default will will try to hit path `GET /` and expect a `2xx` status code * `path` - optional path to hit for health check. Defaults to `GET /` * `status` - optional status code to expect. Defaults to `2xx` > [!WARNING] > > Changing `id` or `prefix` will swap the resource with a new one in the next deployment. Note that `init` is an array. So you can add any number of these jobs. They will be run in the order you have declared here. ```json theme={null} { "init": [ { "id": "migrate", "prefix": "migrate", "cmd": "python3 manage.py migrate", "env": { "var": "value" } }, { "id": "seeddb", "prefix": "seeddb", "cmd": "python3 manage.py seed", "env": { "var": "value" } }, { "id": "adhoc", "prefix": "adhoc", "image": "alpine/curl:8.14.1", "cmd": "curl -fsSL https://www.google.com/", "env": { "var": "value" } } ] } ``` ### Environment variables Environment variables passed here are not the only ones passed into the job. Following set are injected into the job automatically, in the order mentioned here: 1. Any variable you have added in LocalOps console UI are passed to the job. 2. In addition, any cloud `dependencies` > `exports` variables you declared using below and 3. If this is running as part of a preview service, preview service `previews.depdendencies` > `exports` variables are added too. 4. Variables in `env` above init job config Variables defined in the set #4 overrides the ones defined in say, #3 above. ### Order and errors Jobs are run in the order defined in the array. If any of the init jobs fail to complete successfully, deployment fails and the main `web` service won't start. ## Health Checks For your service, you can define health checks using any one of the following methods. ### Types of Health checks: 1. Shell command 2. HTTP check 3. TCP check 4. gRPC check Checks will be done on each container of your service. Containers are marked as healthy if their corresponding health checks pass for at least once. You can define how often checks have to be carried out using `interval`. And you can define `delay` to tell us how long to wait to start making those checks, during the first time. Use `timeout` to set how long (in seconds) a single check can take before it is counted as a failure. If left blank, `timeout` defaults to `10` seconds. If your container fails these checks beyond `failure_threshold`, the corresponding container will be restarted automatically. ### Example configurations: #### Shell command ```json theme={null} { "health": { "cmd": ["/bin/sh", "-c", "some_executable_or_script"], "delay": 5, //seconds to wait, first time "interval": 5, //seconds between checks "timeout": 10, //seconds per check; default: 10 "failure_threshold": 3 } } ``` #### HTTP Check ```json theme={null} { "health": { "http": { "path": "/health", //optional; default: /; "port": 3000 }, "delay": 5, "interval": 5, "timeout": 10, "failure_threshold": 3 } } ``` #### TCP Check ```json theme={null} { "health": { "tcp": { "port": 3000 //required }, "delay": 5, "interval": 5, "timeout": 10, "failure_threshold": 3 } } ``` When a socket cannot be created with your container on the defined port, health checks will fail. #### gRPC Check ```json theme={null} { "health": { "grpc": { "port": 2379 //required }, "delay": 5, "interval": 5, "timeout": 10, "failure_threshold": 3 } } ``` ## Configure ingress Each environment runs an nginx ingress in front of your services. These settings control how it handles requests on their way to your containers - how long it waits, how much it will buffer, and whether it terminates TLS at all. ### Request timeouts You can tune how long the platform keeps client connections to your service open. This is useful for real-time applications that rely on long-lived TCP connections (eg., websockets, server-sent events, long polling, streaming APIs). ```json theme={null} { "send_timeout": 600, "read_timeout": 600, } ``` | Field | Description | Default (sec) | | - | - | - | | `connection_timeout` | Maximum time (in seconds) platform waits to establish a succesful tcp connection with your service containers, before giving up. | `10` | | `send_timeout` | Maximum time (in seconds) between two successive writes from platform to your service when processing a request from clients. | `120` | | `read_timeout` | Maximum time (in seconds) between two successive read operations that platform waits to read responses from your service while sending them to client | `120` | > [!NOTE] > > The maximum allowed value for each of these timeouts is `3600` seconds (1 hour). > [!NOTE] > > These timeouts apply only to `web` (external), as they govern incoming HTTP requests from public internet routed through platform's ingress. ### Request body size Every environment's ingress accepts request bodies up to `30` MB by default. A client sending more than that gets a `413 Request Entity Too Large` back from the ingress, before the request reaches your container. If your service accepts larger uploads - file attachments, media, bulk imports - raise the limit with `request_body_size`, in whole MB: ```json theme={null} { "request_body_size": 100 } ``` | Field | Description | Default (MB) | | - | - | - | | `request_body_size` | Maximum size (in MB) of a request body the platform accepts for this service. | `30` | The maximum allowed value is `1024` MB (1 GB). A larger value is clamped to it. A zero or negative value is ignored and the `30` MB default is used. > [!NOTE] > > `request_body_size` applies only to `web` (external) services, as it governs incoming HTTP requests from the > public internet routed through the platform's ingress. It is also ignored when > [`ssl_passthrough`](#ssl-passthrough) is enabled, because the ingress forwards those connections without inspecting > HTTP. > [!TIP] > > For very large files, prefer uploading directly to object storage with a presigned URL instead of routing the bytes > through your service. The ingress buffers the whole body before it forwards the request, so large uploads add latency > and load regardless of this setting. ### Response buffers The platform's ingress reads each response from your service into a set of fixed-size buffers before it forwards the response to the client. The first buffer has to hold the whole set of response headers. By default your service gets `8` buffers of `8` KB each. Services that return large headers - long `Set-Cookie` values, SSO or JWT tokens, big `Authorization` headers - can overflow that first buffer. When they do, the ingress fails the request with a `502 Bad Gateway`, and its logs carry `upstream sent too big header while reading response header from upstream`. Raise `proxy_buffer_size` (in KB) to fix it: ```json theme={null} { "proxy_buffer_size": 32, "proxy_buffers": 16 } ``` | Field | Description | Default | Allowed range | | - | - | - | - | | `proxy_buffer_size` | Size (in KB) of each buffer. The first one must fit your service's entire response headers. | `8` | `4` to `64` | | `proxy_buffers` | How many of those buffers the ingress uses per in-flight response. | `8` | `2` to `32` | Both take whole integers. A value outside the allowed range is clamped to the nearest limit. A zero or negative value is ignored and the default is used. Fixing a `502` on response headers needs only `proxy_buffer_size`. `proxy_buffers` controls how much of the response body the ingress holds in memory while streaming it - raising it can help a service that returns large responses to slow clients, and leaving it alone is fine. Declaring either field applies the pair, so a service that sets only one still buffers against the default for the other. > [!NOTE] > > These settings apply only to `web` (external) services, and are ignored when > [`ssl_passthrough`](#ssl-passthrough) is enabled, because the ingress forwards those connections without inspecting > HTTP. > [!NOTE] > > These buffers are per in-flight response, in an ingress controller shared by every service in the environment, which > is why the ceiling is deliberately low. A response larger than `proxy_buffer_size` x `proxy_buffers` is not failed - > the ingress spills the remainder to disk and keeps streaming it. ### SSL passthrough By default, the environment's nginx ingress terminates TLS for incoming traffic and forwards plain HTTP to your service. If your service needs to handle TLS termination itself (eg., for mTLS, custom certificate handling, or protocols that require end-to-end TLS), set `ssl_passthrough` to `true`: ```json theme={null} { "ssl_passthrough": true } ``` When `ssl_passthrough` is enabled, the ingress forwards the raw TLS connection to your container without decrypting it. For this to work, set your service's port to `443` so the ingress can route HTTPS traffic directly to it. Your container must present a valid TLS certificate on that port. ## Deploy timeout When you push a change, LocalOps waits for the new version of your service to roll out and become ready. By default it waits for 5 minutes. If the rollout hasn't become ready by then, the deployment is failed. If your service genuinely needs longer - large images, slow warm up, heavy work done at container startup - set `deploy_timeout` (in seconds): ```json theme={null} { "deploy_timeout": 900 } ``` | Field | Description | Default | | - | - | - | | `deploy_timeout` | Time (in seconds) to wait for your service's rollout to become ready, before failing the deployment. | `300` | Allowed range is `60` (1 minute) to `1200` (20 minutes). If you declare a value outside this range, LocalOps clamps it to the nearest limit and tells you so in the deployment logs. A zero or negative value is ignored and the default is used. > [!NOTE] > > Services running on Windows node groups wait for `900` seconds (15 minutes) by default, as image pull and container > startup are slower there. > [!NOTE] > > `deploy_timeout` covers only the wait for your service to become ready. Cloning your repository, building the image > and pushing it happen before this, and are not governed by this setting. Every deployment logs the wait it is going to use, like `Waiting up to 15m0s for this service's rollout to become ready`. Check your deployment logs to confirm that the value you declared was picked up. ## Autoscaling Add an `autoscaling` block to add and remove replicas with load, instead of running a fixed number of containers all day. Scale on CPU or memory utilization, on time-of-day windows, or both: ```json theme={null} { "autoscaling": { "max_replicas": 10, "target_cpu": 70 } } ``` `max_replicas` is required and is never defaulted - it is the ceiling on what this service can cost. There is no `min_replicas` - the floor is always your service's container count. `target_cpu` and `target_memory` are percentages of each pod's CPU and memory request, so the service needs a minimum CPU or memory set under the Scaling tab for them to work. Preview environments never autoscale, and neither do cron services, job services or services declaring a `disk` volume. See [Autoscaling](/environment/services/autoscaling) for the full guidance - schedules, the replica bounds, setting the same config from the console instead, and what gets clamped rather than failing your deployment. ## BEAM clustering If you run Elixir or Erlang services, add `beam_cluster_id` with the same value in every service you want clustered together. LocalOps labels all their pods alike and creates a shared headless service whose DNS returns every member pod's IP, then injects `LOPS_BEAM_CLUSTER_NAME` and `LOPS_BEAM_CLUSTER_DNS` so `libcluster` can discover peers. ```json theme={null} { "beam_cluster_id": "myapp" } ``` To cluster across regions, also set `beam_dns_name` to a record in a private DNS zone shared by all your regional VPCs. LocalOps keeps that record pointed at the environment's pods so nodes in other regions can find them. ```json theme={null} { "beam_cluster_id": "b2bapp", "beam_dns_name": "mumbai.mesh.acmecorp.internal" } ``` See [BEAM clustering](/environment/services/beam-clustering) for the full guidance — wiring up `libcluster`, clustering across regions, the release config you still own, and how previews, jobs and crons behave. ## Privileged containers Some workloads need to reach the node they run on - eBPF agents, kernel module loaders, low level profilers, or code that talks to host devices. These need more privileges than a normal container gets. Declare `unsafe.privileged` to run your service's container in privileged mode: ```json theme={null} { "unsafe": { "privileged": true } } ``` This applies only to your service's own container. [Init jobs](/environment/services/ops-json#init-jobs) and [processes](/environment/services/ops-json#configuring-processes) continue to run unprivileged, so the extra privilege stays limited to the workload that asked for it. > [!WARNING] > > A privileged container can access host devices and effectively bypasses container isolation on the node it runs on. > Only enable this when your workload genuinely requires node level access, and keep such code in a dedicated service > instead of your main application service. Leaving `unsafe` out, or setting `"privileged": false`, keeps the default behaviour - your service runs unprivileged. ## Volumes Your service may need scratch space to write temporary files, a durable disk that survives restarts, or a set of certificate files mounted into a well known path. Declare them once under the top-level `volumes` key and LocalOps provisions them for you. There are no Kubernetes manifests to write and no storage class to pick. The same declaration works identically on AWS and GCP, and it drives both the service running in your environment and the [Helm chart you generate](/use-cases/self-hosted) for customers. ```json theme={null} { "volumes": [ { "name": "tmp", "mount_path": "/tmp", "kind": "mem" }, { "name": "run", "mount_path": "/var/run", "kind": "mem" }, { "name": "tmpfiles", "mount_path": "/app/src/tmpfiles", "kind": "disk", "size": "10Gi", "expose": true }, { "name": "temporal-tls", "mount_path": "/etc/temporal/tls", "kind": "secret", "secret_name": "temporal-tls", "expose": true } ] } ``` Volumes apply to the service itself. Every container that runs for the service gets the mounts, including the [init jobs](/environment/services/ops-json#init-jobs) that run before it starts. ### Volume arguments | Key | Required | Description | | - | - | - | | `name` | Yes | Your identifier for the volume. Lowercase letters, numbers and `-`, starting and ending with a letter or number, at most 59 characters, unique within the service. This is also the key you will see in the generated Helm chart, so pick something you are happy reading later. | | `mount_path` | Yes | Absolute path inside the container. Must be unique within the service. | | `kind` | Yes | One of `mem`, `disk` or `secret`. See [Kinds of volumes](/environment/services/ops-json#kinds-of-volumes) below. | | `size` | `disk` only | A quantity like `10Gi` or `512Mi`. Required for `disk`. Optional on `mem`, where it changes the behaviour. Not accepted on `secret`. | | `secret_name` | `secret` only | Name of the Kubernetes secret to mount. Not accepted on other kinds. | | `expose` | No | Publishes one setting for this volume into the generated chart's `values.yaml`. Valid on `disk` and `secret` only. | ### Kinds of volumes #### `mem` - scratch space Scratch space that is discarded when the container goes away. This is what you want for paths like `/tmp` and `/var/run` when your image runs with a read-only root filesystem. By default it is backed by the disk of the machine your service runs on. Add a `size` and you get a RAM disk instead. ```json theme={null} { "volumes": [ { "name": "tmp", "mount_path": "/tmp", "kind": "mem" }, { "name": "cache", "mount_path": "/cache", "kind": "mem", "size": "256Mi" } ] } ``` The first one is backed by the machine's disk. The second is a 256Mi RAM disk. > [!WARNING] > > A RAM disk counts against the memory limit of your service. Size it deliberately - files written there consume the > same memory your application code needs. #### `disk` - durable storage Storage that survives restarts and rescheduling. `size` is required. Disks are encrypted, are created in the same zone as the service that uses them, and can be grown later by raising `size` and deploying again. Each replica of your service gets its own disk and keeps it across restarts, rather than all replicas sharing one. ```json theme={null} { "volumes": [ { "name": "tmpfiles", "mount_path": "/app/src/tmpfiles", "kind": "disk", "size": "10Gi" } ] } ``` Disks are available on [web](/environment/services/web), [internal](/environment/services/internal) and [worker](/environment/services/workers) services. > [!NOTE] > > Disks are not available on [cron](/environment/services/cronjob) or [job](/environment/services/job) services, where > each run gets a fresh short-lived container and durable storage does not mean much. Declaring one there fails the > deployment. #### `secret` - mount a secret as files Mounts an existing Kubernetes secret into the container as read-only files. Each key in the secret becomes a file inside `mount_path`. ```json theme={null} { "volumes": [ { "name": "temporal-tls", "mount_path": "/etc/temporal/tls", "kind": "secret", "secret_name": "temporal-tls" } ] } ``` A secret with a key called `cert` shows up at `/etc/temporal/tls/cert`. This works on every service type. The secret must already exist in the same environment - LocalOps mounts it, it does not create it for you. To pass values as environment variables instead, use [secrets](/environment/services/secrets). ### Volumes in the generated Helm chart The same `ops.json` drives the [Helm chart you generate](/use-cases/self-hosted) from your environment, so your service behaves the same when a customer installs it in their own EKS or GKE cluster. Volumes marked `expose: true` show up in the chart's `values.yaml` under `persistence`, keyed by the `name` you chose. Volumes you don't mark do not appear there at all - they are still mounted, they are just not something the person installing the chart can change. ```yaml theme={null} webapp: replicaCount: 3 persistence: # /app/src/tmpfiles 'tmpfiles': size: 10Gi # /etc/temporal/tls 'temporal-tls': secretName: '' ``` A `disk` exposes its `size`: ```bash theme={null} helm install acme ./chart --set webapp.persistence.tmpfiles.size=50Gi ``` A `secret` exposes its `secretName` and defaults to blank. The mount is only created when a name is supplied, so a stock install neither mounts it nor requires the secret to exist. That matters when the feature backed by that secret is turned off for a given customer. To enable it: ```bash theme={null} helm install acme ./chart --set webapp.persistence.temporal-tls.secretName=my-tls ``` Mount paths and kinds stay fixed. They are part of how your app works, rather than something whoever installs the chart should be changing - `size` and `secretName` are the only settings exposed. > [!NOTE] > > `expose` only affects the generated chart. In a LocalOps environment, a declared `secret` volume is always mounted, > because you control both the `ops.json` and the secret. ### Validation The `volumes` block is checked before anything is deployed. A problem fails the deployment with a message naming the entry, instead of leaving you with a container that won't start. These are rejected: * A missing or malformed `name`, a duplicate `name`, or a duplicate `mount_path` * A `mount_path` that is not an absolute path * A missing or unknown `kind` * A `disk` without a `size`, or a `size` that is not a valid quantity like `10Gi` * A `disk` on a `cron` or `job` service * A `secret` without a `secret_name`, or a `secret` with a `size` * `secret_name` on a `mem` or `disk` volume * `expose` on a `mem` volume > [!NOTE] > > Volumes apply to the service's own containers. They are not added to additional processes declared under > [`processes`](/environment/services/ops-json#configuring-processes). > [!NOTE] > > Volumes are supported on AWS and GCP today. Azure support is coming soon. ## Automatic provisioning of cloud resources Your service may need a S3 bucket to store files, RDS instance to host your Postgres/MySQL/SQL Server database or Redis database for caching, background jobs, etc., You can declare these dependencies once in `ops.json`. LocalOps will provision these resources and ensure they are active & enabled for your service to use. ### How to provision a cloud resource In your `ops.json`, write a key called `dependencies` and fill up your dependency in the following format. ```json theme={null} { "dependencies": { "": { "": [ { "id": "", "prefix": "", //"...any other resource specific config", "exports": { "ENV-VAR-KEY": "$resource-property", "ENV-VAR-KEY2": "$resource-property2" } } ] } } } ``` You can define any number of cloud resources (say, buckets) for a given cloud resource type (S3). Here is an example: ```json theme={null} { "dependencies": { "s3": { "buckets": [ { "id": "attachments", "prefix": "attachments", "exports": { "ATTACHMENTS_BUCKET_ARN": "$arn", "ATTACHMENTS_BUCKET_NAME": "$name" }, "skip_preview": false, "preview_only": false } ] } } } ``` ### ID (`id`) Specify a unique alpha numeric string that is unique amongst all the other resouces of same resource type (say S3). LocalOps uses this to uniquely identify the resource, provision and manage it on your behalf in your cloud. If you change the ID (`id`), the resource will be deleted and replaced by any other new one. ### Prefix (`prefix`) You can provide a prefix string to use in the name of all resources. In the above case, bucket created will have a name like `attachmentsbucket-23490823940`. If you change prefix string, the resource will be deleted and replaced by any other new one. ### Environment Variables (`exports`) LocalOps automatically injects environment variables for each provisioned resource to your service contaienrs. You can define the environment variable keys and specify the properties of the cloud resource to fill it up. So in above example, LocalOps will form an environment variable by the name `ATTACHMENTS_BUCKET_ARN` and pass ARN of the new S3 bucket to it. So that in your code, you can use it like: ```nodejs theme={null} console.log("bucket arn:", process.env.ATTACHMENTS_BUCKET_ARN) ``` ### Skip preview (`skip_preview`) The specific resource isn't considered for preview services / ephemeral environments if this is `true`. ### Preview only (`preview_only`) The specific resource is considered only for preview services / ephemeral environments if this is `true`. ### Overall Lifecycle Resources are read from `ops.json` when the [service](/environment/services/create) is being [deployed](/environment/services/deploy). 1. If the resource dependency with the given `id` is seen for the first time, it is provisioned. 2. If the resource dependency with the an existing `id` is missing, it is deleted automatically during the next service deployment . 3. If any of the resource dependency properties are modified, they are updated automatically during the next service deployment. ### Accessing cloud resources Your code can access these resources using the environment variables defined in `ops.json`. For example, you can add files/objects to the S3 bucket you defined in `ops.json` (see above), for example: ```ts theme={null} import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'; const s3 = new S3Client({ region: process.env.AWS_REGION }); const upload = async () => { await s3.send( new PutObjectCommand({ Bucket: process.env.ATTACHMENTS_BUCKET_NAME, // NOTE! This is the same env var you defined in ops.json Key: 'hello.txt', Body: 'Hello there!', ContentType: 'text/plain', }), ); console.log('✅ Uploaded!'); }; upload().catch(console.error); ``` #### Automatic role based access In AWS based environments you spin up, every container (your code) runs with a pre-configured IAM role that provides implicit, authenticated, key-less access to any cloud resource (say S3). You can see the name of pre-configured IAM role in environment's dashboard. Any IAM policy can be added to the pre-configured role to give your code appropriate access to cloud resources. For the resources defined in `ops.json`, LocalOps automatically generates necessary IAM permissions and add them as policies in the pre-conigured IAM role. Your code can just access the resources defined in `ops.json` by name and all calls made will be authenticated calls by default. For example, for the S3 bucket defined in `ops.json`, LocalOps automatically adds the following necessary IAM permissions in the pre-configured IAM role. * Read and write objects * List bucket contents ``` { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::your-bucket-name", "arn:aws:s3:::your-bucket-name/*" ] } ``` ### Supported cloud resources As of now, you can define the following dependencies in `ops.json`. We plan to grow this list to cover other services in AWS. Please get in touch with us at [support@localops.co](mailto:support@localops.co) if you need anything specific. | Resource | Use it for | Docs | | - | - | - | | Amazon S3 buckets | Static object storage (files, pictures, etc.,) | [S3](/environment/services/aws/s3) | | Amazon RDS instances | Hosting Postgres, MySQL, SQL Server databases | [RDS](/environment/services/aws/rds) | | Amazon Aurora clusters | Auto-scaling Postgres/MySQL, read endpoint | [Aurora](/environment/services/aws/aurora) | | Amazon ElastiCache | Caching, queues, pub/sub | [ElastiCache](/environment/services/aws/elasti-cache) | | Amazon SNS topics | Pub/sub capabilities | [SNS](/environment/services/aws/sns) | | Amazon SQS queues | Queueing (standard/FIFO) capabilities | [SQS](/environment/services/aws/sqs) | | Amazon MSK clusters | Kafka event streaming (provisioned/serverless) | [MSK](/environment/services/aws/msk) | ### Configured for production use, by default All cloud resources are configured with production-grade security: * **Encryption at rest**: Enabled by default, for all data storage services (S3, RDS, Aurora, Elastic Cache) * **Network isolation**: Resources are deployed within your environment's VPC wherever applicable. * **Private only**: Resources are deployed for private access only, from within your environment's VPC wherever applicable. * **Access control**: Least-privilege access is configured by default for applicable resources, using fine-grained IAM policies and IAM role. * **High availability**: Multi AZ setup is supported in configuration and can be turned on when needed * **Monitoring**: Cloudwatch monitoring is turned on by default for applicable cloud resources. These metrics and logs can be seen inside out [built-in monitoring dashboard](/environment/monitoring/metrics). * **Backups tuned on**: Backups are turned ON for all applicable data storage services (RDS, Elastic Cache) with 30-day retention. ### Tuned For Ephemeral Preview environments LocalOps can spin up ephemeral preview environments for your service, for each Github pull request to the configured target branch of the service. Configuration for the supported cloud resources are tuned differently for these preview environments. To ensure * preview environments come up fast * preview enviromments don't incur a lot of costs (say in the case of RDS) Following configurations are disabled in Pull request preview environments: 1. Backups 2. Cloudwatch monitoring 3. Multi-AZ setup 4. Encryption ## Ephemeral databases and services for pull request previews LocalOps can spin up a preview environment / preview service / ephemeral copy for your service when a pull request is raised at the configured target branch of a service. For each of these preview services, you can spin up isolated set of databases, caches, queues and workers that are created and deleted when the PR is opened and closed/merged. Following resources can be created this way: 1. Databases - Postgres / MySQL 2. Cache services - Redis / Memcache 3. Queues - RabbitMQ 4. Workers - using your code or any public docker image Each of these can be declared under a top-level key called `previews`, like below: ```json theme={null} { "previews": { "dependencies": { "db": [ { "id": "db", "prefix": "db", "engine": "postgres", "version": "17.5", "exports": { "DB_HOST": "$host", "DB_PORT": "$port", "DB_USER": "$user", "DB_NAME": "$db", "DB_PASS": "$pass" } } ], "cache": [ { "id": "redis", "prefix": "redis", "engine": "redis", "version": "8.0.3", "exports": { "REDIS_HOST": "$host", "REDIS_PORT": "$port" } } ], "queues": [ { "id": "rabbitmq", "prefix": "rabbitmq", "engine": "rabbitmq", "version": "4", "exports": { "QUEUE_HOST": "$host", "QUEUE_PORT": "$port", "QUEUE_VHOST": "$vhost", "QUEUE_USER": "$user", "QUEUE_PASS": "$pass" } } ] }, "workers": [ { "id": "worker", "prefix": "worker", "cmd": "node server.js", "env": { "variable": "value" }, "count": 2 } ] } } ``` ### Isolated databases You can spin up any number of these databases for each PR, with any publicly available version: 1. Postgres 2. Mysql LocalOps automatically provisions, configures and runs these databases in your environment, just by declaring the name, database and version in your `ops.json`. In the `ops.json`, just define a key called `db` under `previews` > `dependencies` like below and add your database dependencies as an array. Example: ```json theme={null} { "previews": { "dependencies": { "db": [ { "id": "db1", "prefix": "db1", "engine": "postgres", "version": "17.5", "exports": { "DB1_HOST": "$host", "DB1_PORT": "$port", "DB1_USER": "$user", "DB1_NAME": "$db", "DB1_PASS": "$pass" } }, { "id": "db2", "prefix": "db2", "engine": "postgres", "version": "17.5", "exports": { "DB2_HOST": "$host", "DB2_PORT": "$port", "DB2_USER": "$user", "DB2_NAME": "$db", "DB2_PASS": "$pass" } } ] } } } ``` Configuration for each `db`: 1. `id` - Unique identifier to identify this resource within the environment 2. `prefix` - String that will be used as prefix in the name of the resource 3. `engine` - `mysql` or `postgres` 4. `version` - any public version of [mysql](https://hub.docker.com/_/mysql) or [postgres](https://hub.docker.com/_/postgres) available in docker hub 5. `exports` - Information of the database resource can be exported to be used within your service. Define a set of key value pairs that will be injected as environment variables in your service. Keys will be injected as such. Values are interpreted as follows. Export values: 1. `$host` - DNS host of the resource, privately reachable within the cluster. All resources are private. 2. `$port` - DNS port of the resource. For eg., you will see \$port set as `3306` for MySQL and `5432` for Postgres. 3. `$db` - Database name to use from your code to read/write data. LocalOps creates a default database for you when provisioning the database server. 4. `$user` - Username to use while authenticating into the database. LocalOps creates a default user for you when provisioning the database server and you can use this variable to get its value injected in your environment variable. 5. `$pass` - Password to use while authenticating into the database. LocalOps creates this for you and passes it to you via this var. > [!WARNING] > > Changing `id` or `prefix` will swap the resource with a new one in the next deployment. > [!WARNING] > > > > All databases are ephemeral databases only. No persistent storage is configured, as they are created for previewing > pull requests only. ### Isolated cache servers You can spin up any number of these caching servers for each PR, with any publicly available version: 1. Redis 2. Memcache LocalOps automatically provisions, configures and runs these servers in your environment, just by declaring the name, engine and version in your `ops.json`. In the `ops.json`, just define a key called `cache` under `previews` > `dependencies` like below and add your caching dependencies as an array. Example: ```json theme={null} { "previews": { "dependencies": { "cache": [ { "id": "redis", "prefix": "redis", "engine": "redis", "version": "8.0.3", "exports": { "REDIS_HOST": "$host", "REDIS_PORT": "$port" } } ] } } } ``` Configuration for each `cache`: 1. `id` - Unique identifier to identify this resource within the environment 2. `prefix` - String that will be used as prefix in the name of the resource 3. `engine` - `redis` or `memcache` 4. `version` - any public version of [redis](https://hub.docker.com/_/redis) or [memcache](https://hub.docker.com/_/memcached) available in docker hub 5. `exports` - Information of the caching server can be exported to be used within your service. Define a set of key value pairs that will be injected as environment variables in your service. Keys will be injected as such. Values are interpreted as follows. Export values: 1. `$host` - DNS host of the resource, privately reachable within the cluster. All resources are private. 2. `$port` - DNS port of the resource. For eg., you will see \$port set as `6379` for Redis and `11211` for Memcache. > [!WARNING] > > Changing `id` or `prefix` will swap the resource with a new worker in the next deployment. > [!WARNING] > > > > All caching servers are ephemeral services only. No persistent storage is configured, as they are created for > previewing pull requests only. ### Isolated queue/messaging servers You can spin up any number of these queueing/messaging servers for each PR, with any publicly available version: * RabbitMQ LocalOps automatically provisions, configures and runs these servers in your environment, just by declaring the name, engine and version in your `ops.json`. In the `ops.json`, just define a key called `queues` under `previews` > `dependencies` like below and add your dependencies as an array. Example: ```json theme={null} { "previews": { "dependencies": { "queues": [ { "id": "rabbitmq", "prefix": "rabbitmq", "engine": "rabbitmq", "version": "4.1.2", "exports": { "QUEUE_HOST": "$host", "QUEUE_PORT": "$port", "QUEUE_VHOST": "$vhost", "QUEUE_USER": "$user", "QUEUE_PASS": "$pass" } } ] } } } ``` Configuration for each `cache`: 1. `id` - Unique identifier to identify this resource within the environment 2. `prefix` - String that will be used as prefix in the name of the resource 3. `engine` - `rabbitmq` 4. `version` - any public version of [rabbitmq](https://hub.docker.com/_/rabbitmq) available in docker hub 5. `exports` - Information of the messaging/queueing server can be exported to be used within your service. Define a set of key value pairs that will be injected as environment variables in your service. Keys will be injected as such. Values are interpreted as follows. Export values: 1. `$host` - DNS host of the resource, privately reachable within the cluster. All resources are private. 2. `$port` - DNS port of the resource. For eg., you will see \$port set as `5672` for RabbitMQ. 3. `$vhost` - Virtual host of rabbitmq that is created for you to use. 4. `$user` - Username to use while authenticating into this server. LocalOps creates a default user for you when provisioning the RabbitMQ server and you can use this variable to get its value injected in your environment variable. 5. `$pass` - Password to use while authenticating into this server. LocalOps creates this for you and passes it to you via this variable. Get in touch with us at [support@localops.co](mailto:support@localops.co) if you want more queueing servers supported. > [!WARNING] > > Changing `id` or `prefix` will swap the resource with a new one in the next deployment. > [!WARNING] > > > > All queueing servers are ephemeral services only. No persistent storage is configured, as they are created for > previewing pull requests only. ## Configuring Processes You can spin up any number of processes inside each service * Run any publicly available docker image from Docker hub * Run your existing code from with a different start command Example: ```json theme={null} { "processes": [ { "id": "worker", "prefix": "worker", "image": "nginx:1.29", "cmd": "node server.js", "count": 2, "env": { "variable": "value" } } ] } ``` Configuration for each `worker`: 1. `id` - Unique identifier to identify this resource within the environment 2. `prefix` - String that will be used as prefix in the name of the resource 3. `image` - Image name with tag/version. Eg., `nginx:1.29`. This is optional. If the `image` is not provided, we use the same image that was used to run your original service, which was built with the latest commit in your PR. 4. `cmd` - start command. Used on the `image` you provide in this config or the image LocalOps built using latest commit in your PR. Refer to [run command in service](/environment/services/create#run-command) for more details 5. `env` - Pass any environment variable necessary to run this image. In addition, when you don't provide an `image` in this config, the image LocalOps built using latest commit in the PR will be used and all the secrets you added for this service in LocalOps console UI will also be injected into the worker. 6. `count` - Number of replicas / containers of the worker to run > [!WARNING] > > Changing `id` or `prefix` will swap the resource with a new one in the next deployment. ## Configuring Cron service It is a common pattern in many codebases and communities, to define cron logic inside HTTP request handlers and call those HTTP endpoints on a specific schedule. You can do the same here in `ops.json`. ```json theme={null} { "cron": { "cron_jobs": [ { "schedule": "*/2 * * * *", "path": "/api/v1/do-every-2-mins" }, { "schedule": "0 0 * * *", "path": "/api/v1/do-every-morning" } ] } } ``` ### Cron arguments Define `cron` key in `ops.json` and add any number of scheduled hits by giving * schedule: Specify a spechedule using the same powerful crontab syntax. [Refer here](https://crontab.guru/) on how to define this. * path: Specify a path to hit. Your service's internal HOST is known at run time and hence you don't have to define the URL like `https:///path`. LocalOps spins up an [implicit cron service](https://hub.docker.com/r/localopsroot/opscron) within your environment, to make the API calls to your service using its private Internal host name, as per the above schedule. Crons only work if your service is either an "external/web serivce" or "internal" service. So that there are endpoints available to hit based on a schedule. ## Complete Example Here's a comprehensive `ops.json` example: ```json theme={null} { "beam_cluster_id": "myapp", "deploy_timeout": 900, "autoscaling": { "max_replicas": 10, "target_cpu": 70, "schedules": [ { "days": ["monday", "tuesday", "wednesday", "thursday", "friday"], "start_time": "09:00", "end_time": "18:00", "timezone": "Asia/Kolkata", "replicas": 6 } ] }, "volumes": [ { "name": "tmp", "mount_path": "/tmp", "kind": "mem" }, { "name": "tmpfiles", "mount_path": "/app/src/tmpfiles", "kind": "disk", "size": "10Gi", "expose": true }, { "name": "temporal-tls", "mount_path": "/etc/temporal/tls", "kind": "secret", "secret_name": "temporal-tls", "expose": true } ], "init": [ { "id": "migrate", "prefix": "migrate", "image": "nginx:1.29", //optional "cmd": "python3 manage.py migrate", "env": { "var": "migrate" } }, { "id": "seeddb", "prefix": "seeddb", "image": "nginx:stable-bookworm", "cmd": "python3 manage.py seed", "env": { "var": "seed" } } ], "cron": { "cron_jobs": [ { "schedule": "*/2 * * * *", "path": "/api/v1/sync-user-metrics" } ] }, "processes": [ { "id": "my-process-1", "prefix": "worker", "cmd": "node server.js", "env": { "variable": "value" }, "count": 2 } ], "dependencies": { "s3": { "buckets": [ { "id": "user-metrics-bucket", "prefix": "metrics-data", "exports": { "MY_BUCKET_NAME1": "$name", "MY_BUCKET_ARN1": "$arn" } } ] }, "sns": { "topics": [ { "id": "user-alerts-topic", "prefix": "user-alerts", "exports": { "MY_SNS_TOPIC_NAME1": "$name", "MY_SNS_TOPIC_ARN1": "$arn" } } ] }, "sqs": { "queues": [ { "id": "metrics-queue", "prefix": "metrics-events", "exports": { "MY_SQS_QUEUE_NAME1": "$name", "MY_SQS_QUEUE_ARN1": "$arn" } } ] }, "rds": { "instances": [ { "id": "user-data-db", "prefix": "userdata", "engine": "postgres", "version": "17.5", "storage_gb": 10, "instance_type": "db.t4g.small", "publicly_accessible": false, "exports": { "MY_RDS_INSTANCE_NAME": "$name", "MY_RDS_INSTANCE_ARN": "$arn", "MY_RDS_INSTANCE_ENDPOINT": "$endpoint", "MY_RDS_INSTANCE_ADDRESS": "$address", "MY_RDS_INSTANCE_USERNAME": "$username", "MY_RDS_INSTANCE_PASSWORD_ARN": "$passwordArn", "MY_RDS_INSTANCE_DB_NAME": "$dbName" } } ] }, "aurora": { "clusters": [ { "id": "orders", "prefix": "orders", "engine": "aurora-postgres", "version": "16.4", "serverless": { "min_acu": 0.5, "max_acu": 16 }, "replicas": 1, "exports": { "MY_AURORA_CLUSTER_DSN": "$dsn", "MY_AURORA_CLUSTER_READER_DSN": "$readerDsn", "MY_AURORA_CLUSTER_ADDRESS": "$address", "MY_AURORA_CLUSTER_PORT": "$port", "MY_AURORA_CLUSTER_DB_NAME": "$dbName" } } ] }, "elasticache": { "clusters": [ { "id": "session-cache", "prefix": "user-session", "engine": "redis", "version": "7.0", "instance_type": "cache.t4g.small", "num_nodes": 1, "exports": { "MY_ELASTICACHE_CLUSTER_NAME": "$name", "MY_ELASTICACHE_CLUSTER_ARN": "$arn", "MY_ELASTICACHE_CLUSTER_ENDPOINT": "$endpoint", "MY_ELASTICACHE_CLUSTER_ADDRESS": "$address", "MY_ELASTICACHE_CLUSTER_PORT": "$port" } } ] } }, "previews": { "dependencies": { "db": [ { "id": "db", "prefix": "db", "engine": "postgres", "version": "17.5", "exports": { "DB_HOST": "$host", "DB_PORT": "$port", "DB_USER": "$user", "DB_NAME": "$db", "DB_PASS": "$pass" } } ], "cache": [ { "id": "redis", "prefix": "redis", "engine": "redis", "version": "8.0.3", "exports": { "REDIS_HOST": "$host", "REDIS_PORT": "$port" } } ], "queues": [ { "id": "rabbitmq", "prefix": "rabbitmq", "engine": "rabbitmq", "version": "4", "exports": { "QUEUE_HOST": "$host", "QUEUE_PORT": "$port", "QUEUE_VHOST": "$vhost", "QUEUE_USER": "$user", "QUEUE_PASS": "$pass" } } ] } } } ``` # Secrets Source: https://docs.localops.co/environment/services/secrets This guide will explain how to add & use secrets in the environment and inside services. Secrets are sensitive key value pairs that you add at run time to use in your services. You can use secrets to pass credentials to access your database, s3 bucket, OpenAI API, environment name, JWT auth keys, cookie secrets and other environment specific information. > [!NOTE] > > When you save secrets, all secrets are encrypted and stored in your connected cloud account's secret manager. For example, in AWS, all the secrets are encrypted/stored in Parameter Store. > > LocalOps only stores the `KEY` names for reference. ## Usage & environment vars LocalOps securely passes each key value pair as environment variable to your service. So you can read them and use in code as you would do for any other environment variable. ## How to add/update secrets ### During service creation In New Service form, you can see a section called "Secrets". You can add your key value pairs in that section and create the service. If you don't have all secrets handy when you are creating the service, you can add them after service created. We don't deploy a service until you trigger them from UI or via git push. ### After service creation Navigate to Environment > Services > Service section to find "Secrets" tab. In there, you can add/update your secrets anytime. > [!NOTE] > > What you see depends on your [role](/team/understanding-roles#permissions-in-detail): Read-only users don't see the > Secrets tab, Maintainers see secret names but not their values, and Members can see values and add, edit or delete > secrets. ## Environment level vs Service level secrets Secrets can be added at two levels: 1. Environment level 2. Service level Environment level secrets are global secrets that will get passed into every service within the environment implicitly. Service level secrets are added at the service level and override Environment level secrets wherever the name matches with a environment level secret. ## Expressions in secret values A secret value can contain `#{...}` expressions. Each expression is replaced with the value it points to — an environment level secret, another service's secret, or a service's in-cluster hostname. Expressions are evaluated anywhere inside the value, not just when the expression is the whole value. So one secret can hold a complete URL instead of being split into separate host/port/path variables. | Expression | Resolves to | | - | - | | `#{$/KEY}` | Value of the environment level (global) secret `KEY` | | `#{$svc-abc/KEY}` | Value of the secret `KEY` defined in the service with alias `$svc-abc` | | `#{$svc-abc}` | Internal hostname of the service with alias `$svc-abc` | | `#{$svc-abc/service/mongodb}` | Internal hostname of the `mongodb` service created by the Helm chart service `$svc-abc` | `$svc-abc` is the [alias of a service](/environment/services/micro-services#using-service-alias-as-hostname). You can copy it from the "Overview" tab of that service. ### Examples ```bash theme={null} # Global secrets and another service's secret in one value DATABASE_URL=postgres://#{$/PG_USER}:#{$/PG_PASSWORD}@#{$/PG_HOST}:5432/#{$svc-242f/PG_DB} # JDBC URL, host from a Helm chart's postgres service JDBC_URL=jdbc:postgresql://#{$svc-0abc/service/postgresql}:5432/orders?user=#{$/PG_USER}&password=#{$/PG_PASSWORD} # A service created by a Helm chart service MONGO_URL=mongodb://#{$svc-0abc/service/mongodb}:27017/app # Multiple expressions in one value UPSTREAMS=http://#{$svc-242f}:8080,http://#{$svc-242f}:9090 ``` ### What `#{$svc-abc}` resolves to A bare alias resolves only when the referenced service actually has an address inside the cluster. | Service type | `#{$svc-abc}` | | - | - | | `Web`, `Internal` | Resolves to the service's internal hostname. | | `Helm chart` | Does not resolve. The chart names its own services — use `#{$svc-abc/service/}` instead. | | `Worker`, `Cron`, `Job` | Never resolves. These run without a Kubernetes Service, so there is no hostname to hand out. | ### Unresolvable expressions An expression that cannot be resolved is left in the value **exactly as written, braces included**, and a warning is logged. This applies to an unknown alias, a missing secret key, a service with no internal hostname, and any form that isn't in the table above. ```bash theme={null} # $svc-242g does not exist API_URL=http://#{$svc-242g}:8080/x # → http://#{$svc-242g}:8080/x (unchanged) ``` Each expression is resolved independently — one bad expression does not stop the others in the same value. Braces are deliberately kept so a typo is visible in your pod's environment, instead of shipping a plausible looking value like `http://$svc-242g:8080/x` that only fails at runtime. > [!NOTE] > > Expressions are evaluated when you **save** the secret, not on deploy. Create the services you refer to first, then > save the secrets that point at them. > [!WARNING] > > Values are resolved only one level deep. If a referenced secret's value itself contains `$svc-` or `#{...}`, it is > passed through as-is. This is intentional, to break reference loops. ### Bare alias as the whole value A value that is nothing but an alias, with no braces, still resolves to a hostname: ```bash theme={null} CONFIG_SERVER_HOST=$svc-242f ``` This is the older form and is supported for backward compatibility. It follows the same rules as `#{$svc-abc}` above — so a bare alias of a worker, cron, job or Helm chart service stays literal. Prefer `#{...}` for new secrets. ## Importing other service secrets You can also import all the secrets defined in another service by using a special key. ```bash theme={null} __import_svc:$svc-abc ``` Use `__import_svc` as the key and the alias of the service which you want to import as the value. Any secret added in the current service will override the imported secret. ## Aliases outside secrets The same alias rules apply everywhere an alias can be used: * **`ops.json` init dependency** — `"type": "service"` with `"service": "$svc-abc"`. See [Init Jobs](/environment/services/ops-json#init-jobs). An alias that names no in-cluster service fails the deployment with `invalid svc provided as dependency`. * **Helm chart `values.yaml`** — aliases used in the settings of a Helm chart service are replaced with the internal hostname. An alias that doesn't resolve is left as written. ## Expressions in generated Helm charts When LocalOps generates a Helm chart for your environment, `#{...}` expressions are resolved at chart generation time, with two differences: * A referenced secret marked **sensitive** is not substituted — the expression is left as written. A sensitive value cannot be inlined into another secret's value in the chart. * A referenced secret **exposed in the chart** renders as a Helm values reference, for example `{{ .Values.global.config.pgHost }}`, so chart users can override it in their own `values.yaml`. ## Built in secrets Following secrets are passed by default by the platform for convenience. | Secret Key / Environment variable | Value | | - | - | | `LOPS_SVC_HOST` | Public domain of a service. Applicable for `web` service. | | `LOPS_INTERNAL_HOST` | Private internal host name of a service. Applicable for `web` or `internal` services. | | `LOPS_PREVIEW` | `true`/`false` based on whether the service is spun up temporarily for a pull request (PR). | | `POD_IP` | IP address assigned to a pod. | | `HOST_IP` | IP address assigned to the node where the service is running. | | `DEPLOYMENT_ID` | A 24-character alphanumeric string that uniquely identifies the environment (as unique as a UUIDv4). For environments managed by LocalOps, this is unique per environment; for Helm charts generated by LocalOps, this is unique per Helm install. | | `LOPS_INSTANCE_ID` | Same value as `DEPLOYMENT_ID`. A 24-character alphanumeric string that uniquely identifies the environment or Helm install. | ## Deploy changes To propagate any change in secrets, you will have to trigger a new deployment in your service. So that your containers can restart with new and updated env vars. Click on "Deploy" on top right corner of the service section, to do a manual deployment from the latest commit of the configured branch. Or push a new commit to the configured branch and git repo. # Web service Source: https://docs.localops.co/environment/services/web A web service is a service that you want to expose to the public internet, using a public domain and SSL cert. Your users can interact with this service from anywhere. #### Port When you [create a service](/environment/services/create), you must provide `port` number where your Dockerfile exposes the running code. #### Public domain and SSL cert A public domain will be assigned by LocalOps by default. And an auto-renewing SSL cert will be provisioned for the domain. You can setup a custom domain for the service to suit your brand. #### Number of replicas For redundancy, ensure you set at least 2 as the number of replicas. This is a best practice yet you can enter 1 if it better suits your use case. This is a fixed count. To vary it with load instead, see [Autoscaling](/environment/services/autoscaling). #### No downtime deployments All deployments are no-downtime deployments. When LocalOps deploys your code, it brings up new containers with new code first. If they become healthy, old containers will be stopped. #### Logs You can see logs of running containers via the in-built Grafana dashboard. Navigate to Monitor tab to login to Grafana dashboard. Within Grafana dashboard, filter to see `app-services` namespace logs. You can create any number of publicly facing web services. All of the above will be applicable for each of them. # Workers Source: https://docs.localops.co/environment/services/workers A worker is a lot like an internal service that runs continuously yet doesn't expose any service publicly or privately. #### Number of replicas For redundancy, ensure you set at least 2 as the number of replicas. This is a best practice yet you can enter 1 if it better suits your use case. This is a fixed count. To vary it with load instead, see [Autoscaling](/environment/services/autoscaling). #### No downtime deployments All deployments are no-downtime deployments. When LocalOps deploys your code, it brings up new containers with new code first. If they become healthy, old containers will be stopped. #### Logs You can see logs of running worker containers via the in-built Grafana dashboard. Navigate to Monitor tab to login to Grafana dashboard. Within Grafana dashboard, filter to see `app-services` namespace logs. You can create any number of worker services to suit your application architecture. All of the above will be applicable for each of them. # Shared responsibilities Source: https://docs.localops.co/environment/shared-responsibilities Who owns what in a LocalOps environment - your team, LocalOps, and your cloud provider - across apps, infrastructure and security. A LocalOps environment runs your services, on infrastructure LocalOps provisions and configures, inside a cloud account you own. Each of the three parties guards a different layer. Your teamApps, data and account governance Application code & dependencies Container images Service uptime & sizing Secret values Data, schema & retention Domains, allowlists & WAF Peering & network links Cloud account guardrails & CloudTrail Team & cloud access LocalOps account governance GitHub / GitLab account LocalOps platform Environment, configuration and pipelines Dedicated VPC & cluster Network & security groups Encryption at rest SSL certificates Auto-scaling Least-privilege IAM Kubernetes RBAC Automated deployment pipelines Developer experience (DevEx) Secrets delivery Backups set-up Observability stack Your cloud providerAWS, GCP or Azure Data centers & hardware Managed services (EKS, RDS, KMS…) Compute uptime Service uptime & durability In short: * **Your team** owns your services and their uptime, and governs the cloud account they run in. * **LocalOps** provisions the environment, configures it securely, and keeps deployments and the observability stack running. * **Your cloud provider** runs the physical infrastructure and the managed services everything is built on. ## What your team owns ### Your applications * **Code and dependencies.** Bugs, vulnerable libraries, and application-level authentication and authorization are yours to fix. LocalOps controls who can reach a service over the network, not what the service does once a request arrives. * **Container images.** What runs inside your container is defined by your Dockerfile - base image, OS packages, the user it runs as, and which capabilities it needs. Keep base images patched, and run as a non-root user where you can. * **Uptime of your services.** Crashes, memory leaks, slow queries and failing health checks in your app are yours to debug. LocalOps gives you the [logs](/environment/monitoring/logs), [metrics](/environment/monitoring/metrics) and [alerts](/environment/monitoring/alerts) to do it. * **Health checks and resources.** You define [health checks](/environment/services/ops-json) and set CPU and memory for each service, so Kubernetes knows when to restart a container and how much room it has. * **Data inside your services.** What you write to databases, caches, queues and buckets, its schema and migrations, and how long you keep it. ### Your secrets and configuration * **Secret values.** You decide what goes into [secrets](/environment/services/secrets) and when to rotate them, such as third-party API keys. LocalOps stores and delivers them securely. * **Sharing between services.** A service only receives another service's secrets when you import them. Keep imports to what each service needs. * **`ops.json` choices.** Settings that loosen defaults are your call: making a database publicly accessible, [privileged containers](/environment/services/ops-json#privileged-containers), or [SSL passthrough](/environment/services/ops-json#ssl-passthrough) (where your app then owns its own certificate). ### Your cloud account The environment lives in your account, so account-level governance stays with you: * **Cloud account guardrails.** AWS Organizations, service control policies, GuardDuty, Security Hub, AWS Config and budgets are yours to set up. Account-wide defaults, like EBS encryption by default, apply on top of what LocalOps configures. * **CloudTrail.** Every action LocalOps takes in your account is recorded by CloudTrail. Keeping it enabled and retained is up to you. * **The connection role.** You create the role LocalOps uses with CloudFormation, and you can revoke it at any time by deleting the stack. * **Quotas and cost.** Service quotas, reserved capacity and the cloud bill for the resources in your environments. ### Your network edge * **Domains and DNS.** You own your domains, and point [custom domains](/environment/services/custom-domain) at your environment. * **Who can reach a web service.** Per-service IP allowlists, and a WAF like Cloudflare in front of your services, are yours to configure. See [Web application firewall with Cloudflare](/environment/security#web-application-firewall-with-cloudflare). * **Connecting other networks.** VPC peering, Transit Gateway or VPN links to other networks, along with the routes and security group rules they need. Pick a custom CIDR when you create an environment if you plan to peer it. ### Your people * **LocalOps account governance.** Who you invite to LocalOps, what [role](/team/understanding-roles) they get, and removing people who leave. * **Cloud access.** Who in your organisation has direct access to your AWS account outside LocalOps. * **GitHub / GitLab account.** Who can push to the repositories and branches LocalOps deploys from, and which repositories you give LocalOps access to when you connect [GitHub](/accounts/connect-github) or [GitLab](/accounts/connect-gitlab). * **Privileged pod approval.** Allowing privileged containers on a cloud connection is an admin decision you make. ## What LocalOps owns LocalOps provisions and configures everything between your code and the cloud provider, and keeps it working. See Environment security controls on [AWS](/environment/security) and [GCP](/environment/security-gcp) for the full list of what's enabled. * **Environment provisioning.** A dedicated VPC and Kubernetes cluster for every environment, with subnets, NAT, load balancer, ingress, certificates, monitoring and backups set up from the start. * **Secure defaults.** Private subnets, VPC-only security groups for data services, TLS on every web service, encryption at rest, a per-cluster KMS key, and control-plane audit logging. * **Least-privilege access.** Keyless, short-lived access to your account, and per-component IAM roles. Your services' role starts empty and only gains access to the dependencies you declare. * **Cloud resources you declare.** Databases, caches, queues and buckets from `ops.json`, created with encryption, backups and locked-down network access. * **Automated deployment pipelines.** Building your images on every push, rolling them out, and waiting for them to become healthy - one service at a time, without touching the others. * **Developer experience.** The console, [CLI](/cli/usage), [preview environments](/use-cases/ephemeral) for pull requests, and built-in logs and metrics, so your team ships without writing infrastructure code. * **Secrets delivery.** Storing secrets in your account and injecting them into the right containers, and only those. * **SSL certificates.** Issuing and renewing SSL/TLS certificates for every web service and custom domain. * **Auto-scaling.** Adding and removing replicas of your services on CPU, memory and schedules you set in [`ops.json`](/environment/services/autoscaling). * **Observability stack.** Running and keeping available the logs, metrics, dashboards and alerts in each environment. * **Backups set-up.** Backup tooling in each environment, and automated backups for the databases and caches it creates. ## What your cloud provider owns * **Physical infrastructure.** Data centers, hardware, networking and the virtualization layer. * **Compute uptime.** Availability of the virtual machines your nodes run on, and replacing failed underlying hosts. * **Managed services.** Availability and durability of the managed services your environment uses, such as EKS, EC2, RDS, ElastiCache, S3, KMS and STS on AWS. * **Service-level guarantees.** Uptime and durability as defined in each service's SLA. ## Who owns what, at a glance | Area | Your team | LocalOps | Cloud provider | | - | - | - | - | | Application | Code, dependencies, app-level auth, bugs | - | - | | Containers | Image contents, base image patching, runtime user | Running them on the cluster, privileged off by default | - | | Image building and deployment | Dockerfile, pushing to the branch you deploy from | Build infrastructure, building images on every push, storing them, rolling them out | Container registry | | Service uptime | Crashes, health checks, resource sizing | Rollouts, restarts on failed health checks | - | | Scaling | Floors, ceilings and targets in `ops.json` | Auto-scaling replicas to match load | Capacity for new nodes | | Kubernetes cluster | - | Configuration, RBAC, namespaces, add-ons | Managed control plane | | Network | Peering, IP allowlists, WAF, DNS for your domains | VPC, subnets, NAT, load balancer, security groups | Underlying network | | Encryption | Your app's own TLS, if using SSL passthrough | TLS certificates, encryption at rest, KMS keys | Encryption services (KMS) | | Identity and access | Team members and roles, direct cloud access | Keyless connection, per-component IAM roles | IAM and STS | | Secrets | Values, rotation of your own keys | Storage in your account, delivery to the right containers | Parameter Store, Secrets Manager | | Data | What you store, schema, retention | Encrypted, backed-up databases and caches | Durability of storage | | Backups | Restores and deciding what to restore | Backup tooling and automated database backups | Snapshot and backup storage | | Monitoring | Acting on alerts from your services | Logs, metrics, dashboards and alerts stack | CloudWatch, for control-plane logs | | Audit | Keeping CloudTrail enabled and retained | Every action under a named, auditable session | Recording API calls | | Cloud account governance | Guardrails, quotas, cost | - | - | | LocalOps account governance | Members, roles, cloud connections, offboarding | - | - | | GitHub / GitLab account | Repo access, branch protection, who can push | Deploying from the repos you connect | - | | Physical infrastructure | - | - | Data centers, hardware, compute uptime | # .NET Framework/ASP.NET Source: https://docs.localops.co/guides/languages/dotnet Step-by-step guide to setting up a Dockerfile for a .NET Framework application on Windows Server 2022 This documentation provides a step-by-step guide to setting up a Dockerfile for a web API application written using [ASP.NET][aspnet] and [.NET Framework][dotnet]. ## Prerequisites To follow this tutorial, you will need the following: * [Visual Studio 2022](https://visualstudio.microsoft.com/downloads/) with ASP.NET and web development workload. * [.NET Framework 4.7.2 or later](https://dotnet.microsoft.com/download/dotnet-framework) installed. * A basic knowledge of [C#](https://learn.microsoft.com/en-us/dotnet/csharp/) and [ASP.NET Web API][aspnet]. * [Docker Desktop](https://www.docker.com/products/docker-desktop/) configured to use **Windows containers**. > [!NOTE] > > This guide assumes that you have a basic knowledge of the above-mentioned technologies and tools. If you are not > familiar with any of them, it is highly recommended to review their official documentation and tutorials to get up to > speed before proceeding with this guide. > [!WARNING] > > .NET Framework applications require **Windows containers**. Make sure Docker Desktop is switched to Windows containers > mode. Right-click the Docker icon in the system tray and select "Switch to Windows containers" if needed. ## Scaffolding the .NET Framework app Create a new ASP.NET Web API project using Visual Studio: 1. Open Visual Studio 2022 2. Click "Create a new project" 3. Select "ASP.NET Web Application (.NET Framework)" 4. Name the project `DotNetApi` and click "Create" 5. Select "Web API" template and ensure ".NET Framework 4.7.2" is selected 6. Click "Create" ### Hello World! example Open `Controllers/ValuesController.cs` and replace its contents with: ```csharp Controllers/ValuesController.cs theme={null} using System.Web.Http; namespace DotNetApi.Controllers { public class ValuesController : ApiController { // GET api/values public IHttpActionResult Get() { return Ok(new { message = "Hello, World!" }); } // GET api/health [Route("api/health")] public IHttpActionResult GetHealth() { return Ok(new { status = "healthy" }); } } } ``` Run the application by pressing F5 in Visual Studio to verify it works. You should see the API running, and navigating to `/api/values` will return the Hello World JSON response. ## Create the Docker image Dockerizing makes the app run anywhere that supports Windows containers. This guide uses Windows Server 2022 as the base image. ### Create [.dockerignore](https://docs.docker.com/build/building/context/#dockerignore-files) Before creating the Dockerfile, let's create a `.dockerignore` file and add the contents that should not be copied over to the Docker file system. ```ignore .dockerignore theme={null} **/.dockerignore **/Dockerfile **/bin/ **/obj/ **/.vs/ **/.vscode/ **/packages/ **/.git **/.gitignore **/README.md *.user *.suo ``` Read more about [.dockerignore here](https://docs.docker.com/build/building/context/#dockerignore-files). > [!NOTE] > > Creating a `.dockerignore` file and excluding folders like `bin/`, `obj/`, and `packages/` is important since these > contain build artifacts from your local machine. The build will happen inside the Docker container with the correct > platform settings. ### Create Dockerfile Now, create a [Dockerfile](https://docs.docker.com/reference/dockerfile/). The Dockerfile is a text file that contains the instructions for Docker to build the image. The Dockerfile uses [Multi-Stage Builds](https://docs.docker.com/build/building/multi-stage/) which is the recommended approach for .NET Framework applications. This produces a smaller final image by separating the build environment from the runtime environment. > [!TIP] > > Refer to the [official .NET Framework Docker > samples](https://github.com/microsoft/dotnet-framework-docker/tree/main/samples) to learn more about containerizing > .NET Framework applications. ```docker Dockerfile theme={null} # Build stage - uses .NET Framework SDK on Windows Server 2022 FROM mcr.microsoft.com/dotnet/framework/sdk:4.8-windowsservercore-ltsc2022 AS build WORKDIR /app # Copy solution and project files COPY *.sln ./ COPY DotNetApi/*.csproj ./DotNetApi/ COPY DotNetApi/packages.config ./DotNetApi/ # Restore NuGet packages RUN nuget restore # Copy the rest of the source code COPY . ./ # Build the application in Release mode RUN msbuild DotNetApi/DotNetApi.csproj /p:Configuration=Release /p:OutputPath=/app/publish # Runtime stage - uses ASP.NET on Windows Server 2022 FROM mcr.microsoft.com/dotnet/framework/aspnet:4.8-windowsservercore-ltsc2022 AS runtime WORKDIR /inetpub/wwwroot # Copy the published output from the build stage COPY --from=build /app/publish/_PublishedWebsites/DotNetApi . # Expose port 80 (IIS default) EXPOSE 80 ``` > [!NOTE] > > The `mcr.microsoft.com/dotnet/framework/aspnet:4.8-windowsservercore-ltsc2022` image includes IIS and ASP.NET 4.8, > which is fully backward compatible with applications targeting .NET Framework 4.7.x. ### Build Docker image Now you can build the Docker image. To build the Docker image: ```powershell theme={null} docker build -t dotnet-api:latest . ``` This command builds the `dotnet-api` image using Windows containers. > [!NOTE] > > Windows containers do not support cross-platform builds like Linux containers. You must build Windows container images > on a Windows host with Docker configured to use Windows containers. ### Run the Docker image Let's run the Docker container using the image created of the .NET Framework application with the command below. ```powershell theme={null} docker run -d --name dotnet-api -p 8080:80 dotnet-api:latest ``` * `-d`: Runs the container in detached (background) mode. * `--name dotnet-api`: Name of the container `dotnet-api`. * `-p 8080:80`: Maps port 8080 on your host to port 80 in the container (IIS default port). * `dotnet-api:latest` at the end is the name and tag of the image. After running the command, visit `http://localhost:8080/api/values` to see the .NET Framework application running inside the Docker container. To view logs from the container: ```powershell theme={null} docker logs dotnet-api ``` To stop and remove the container: ```powershell theme={null} docker stop dotnet-api docker rm dotnet-api ``` ## Done 🎉 You can now commit and push the Dockerfile to your git repo. [Create a service](/environment/services/create) now to point at the git repository and branch name to deploy this image. [dotnet]: https://dotnet.microsoft.com/download/dotnet-framework [aspnet]: https://learn.microsoft.com/en-us/aspnet/web-api/ # Elixir/Phoenix Source: https://docs.localops.co/guides/languages/elixir Step-by-step guide to setting up a Dockerfile for an Elixir/Phoenix application (with an Erlang/Cowboy variant) and deploying it via LocalOps. This documentation provides a step-by-step guide to setting up a Dockerfile for a web application written using [Phoenix][phoenix] and [Elixir][elixir]. An [Erlang][erlang] variant using [Cowboy][cowboy] and `rebar3` is included at the end. ## Prerequisites To follow this tutorial, you will need the following: * [Elixir][elixir] (v1.17 or later at the time of writing this doc) and the matching [Erlang/OTP][erlang] (OTP 27 or later) installed via [`asdf`](https://asdf-vm.com) or your platform package manager. * [Mix][mix] as the build tool for Elixir. This comes bundled with Elixir. * [Phoenix installer][phoenix-install] (`mix archive.install hex phx_new`). * A basic knowledge of [Elixir][elixir] and [Phoenix][phoenix]. * [Docker] to build standalone containers to serve your production app. > [!NOTE] > > This guide assumes that you have basic knowledge of the above-mentioned technologies and tools. If you are not > familiar with any of them, it is highly recommended to review their official documentation and tutorials to get up to > speed before proceeding with this guide. ## Scaffolding the Phoenix app Create a new Phoenix project. In the following examples, we'll use the project name `hello_app`. The `--no-ecto` flag skips database setup so we can focus on the Dockerfile — drop it if your real app uses a database. ```bash theme={null} mix phx.new hello_app --no-ecto cd hello_app mix deps.get ``` ### Hello World! example Open `lib/hello_app_web/router.ex` and add a simple route at `/` returning JSON: ```elixir lib/hello_app_web/router.ex theme={null} defmodule HelloAppWeb.Router do use HelloAppWeb, :router pipeline :api do plug :accepts, ["json"] end scope "/", HelloAppWeb do pipe_through :api get "/", PageController, :hello get "/health", PageController, :health end end ``` Add the controller at `lib/hello_app_web/controllers/page_controller.ex`: ```elixir lib/hello_app_web/controllers/page_controller.ex theme={null} defmodule HelloAppWeb.PageController do use HelloAppWeb, :controller def hello(conn, _params) do json(conn, %{message: "Hello, World!"}) end def health(conn, _params) do json(conn, %{status: "healthy"}) end end ``` Run the application locally to verify it works: ```bash theme={null} mix phx.server ``` Open `http://localhost:4000` in your browser. You should see `{"message":"Hello, World!"}`. ## Create the Docker image Dockerizing makes the app run anywhere, agnostic of the platform. As long as Docker is installed, whether it's Windows, Mac, or Linux, it can run with the same behavior. The recommended way to ship a Phoenix app in production is as an [Elixir release][release] — a self-contained tarball that bundles the Erlang VM, your compiled code, and all dependencies. It's smaller and faster to boot than running `mix phx.server` in production. ### Generate the release config If you haven't already, generate the release config that Phoenix uses to start your app inside a release: ```bash theme={null} mix phx.gen.release --docker ``` This creates `rel/overlays/bin/server`, `rel/overlays/bin/migrate`, and a starter `Dockerfile` and `.dockerignore` tuned for Phoenix releases. You can use the generated files as-is or customize them with the snippets below. ### Create [.dockerignore](https://docs.docker.com/build/building/context/#dockerignore-files) Before building the image, create a `.dockerignore` file with paths that shouldn't be copied into the build context: ```ignore .dockerignore theme={null} _build deps .elixir_ls .git .gitignore Dockerfile .dockerignore README.md test priv/static node_modules ``` Read more about [.dockerignore here](https://docs.docker.com/build/building/context/#dockerignore-files). > [!NOTE] > > Excluding `_build`, `deps`, and `node_modules` is important — these contain build artifacts from your local machine > that may not match the target platform. The build will happen inside the Docker container with the correct platform > settings. ### Create Dockerfile Now, create a [Dockerfile](https://docs.docker.com/reference/dockerfile/). The Dockerfile uses [Multi-Stage Builds](https://docs.docker.com/build/building/multi-stage/) — a builder stage with the full Elixir toolchain compiles the release, and a tiny Debian slim runtime stage runs it. The final image is typically under 100 MB. ```docker Dockerfile theme={null} # Build stage - uses the official Elixir image with build tools FROM hexpm/elixir:1.17.3-erlang-27.1.2-debian-bookworm-20241016-slim AS build # Install build dependencies RUN apt-get update -y && \ apt-get install -y build-essential git curl && \ apt-get clean && rm -rf /var/lib/apt/lists/* WORKDIR /app # Install hex + rebar RUN mix local.hex --force && mix local.rebar --force # Set build environment ENV MIX_ENV=prod # Copy mix files and fetch deps COPY mix.exs mix.lock ./ COPY config config RUN mix deps.get --only prod RUN mix deps.compile # Copy assets and compile them COPY assets assets COPY priv priv RUN mix assets.deploy # Copy source and compile the app COPY lib lib RUN mix compile # Build the release COPY rel rel RUN mix release # Runtime stage - uses a minimal Debian image FROM debian:bookworm-slim AS runtime # Install runtime dependencies for the BEAM VM RUN apt-get update -y && \ apt-get install -y libstdc++6 openssl libncurses5 locales ca-certificates && \ apt-get clean && rm -rf /var/lib/apt/lists/* # Set the locale RUN sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && locale-gen ENV LANG=en_US.UTF-8 LANGUAGE=en_US:en LC_ALL=en_US.UTF-8 WORKDIR /app RUN chown nobody /app # Copy the release from the build stage COPY --from=build --chown=nobody:root /app/_build/prod/rel/hello_app ./ USER nobody # Default Phoenix port ENV PORT=4000 ENV PHX_SERVER=true EXPOSE 4000 ENTRYPOINT ["/app/bin/server"] ``` > [!NOTE] > > Pin the Elixir, Erlang, and Debian versions in the `hexpm/elixir` tag to match what your team develops against — a > mismatch between local and container OTP versions is the most common source of "works on my machine" surprises with > the BEAM. ### Build Docker image Now you can build the Docker image: ```bash theme={null} docker build --platform linux/amd64 -t hello-app:latest . ``` This command builds the `hello-app` image for platform `linux/amd64` and tags it as `latest`. If you are locally testing your application, you can skip the `platform` key: ```bash theme={null} # only for testing on local machine docker build -t hello-app:latest . ``` ### Run the Docker image Let's run the Docker container using the image created of the Phoenix application. The app needs a `SECRET_KEY_BASE` to start in production — generate one with `mix phx.gen.secret` and pass it via `-e`: ```bash theme={null} docker run \ -it \ --rm \ --name hello-app \ -e PORT=4000 \ -e PHX_SERVER=true \ -e SECRET_KEY_BASE=$(mix phx.gen.secret) \ -d \ -p 4000:4000 \ hello-app:latest ``` * `-it`: enables interactivity with TTY. * `--rm`: tells the Docker Daemon to clean up the container and remove the file system after the container exits. * `--name hello-app`: Name of the container `hello-app`. * `-e PORT=4000`: Sets the HTTP port Phoenix listens on. * `-e PHX_SERVER=true`: Tells the release to start the Phoenix endpoint (releases skip it by default). * `-e SECRET_KEY_BASE=...`: Required signing/encryption secret for sessions and tokens. * `-d`: Runs the container in detached (background) mode. * `-p 4000:4000`: Maps port 4000 on your host to port 4000 in the container. After running the command, visit `http://localhost:4000` to see the Phoenix application running inside the Docker container. To view logs from the container: ```bash theme={null} docker logs hello-app ``` To stop and remove the container: ```bash theme={null} docker stop hello-app ``` ## Erlang variant (Cowboy + rebar3) For Erlang services using [Cowboy][cowboy] directly, the structure is similar — replace Mix with `rebar3` and the Elixir release with an Erlang relx-based release. A minimal `rebar.config`: ```erlang rebar.config theme={null} {erl_opts, [debug_info]}. {deps, [ {cowboy, "2.12.0"} ]}. {relx, [ {release, {hello_app, "0.1.0"}, [hello_app, sasl]}, {dev_mode, false}, {include_erts, true}, {extended_start_script, true} ]}. {profiles, [ {prod, [{relx, [{dev_mode, false}, {include_erts, true}]}]} ]}. ``` The Dockerfile shape is the same — a builder stage compiles the release, a slim runtime stage runs it: ```docker Dockerfile theme={null} FROM erlang:27-slim AS build WORKDIR /app COPY rebar.config rebar.lock ./ RUN rebar3 get-deps COPY src src RUN rebar3 as prod release FROM debian:bookworm-slim AS runtime RUN apt-get update -y && \ apt-get install -y libstdc++6 openssl libncurses5 ca-certificates && \ apt-get clean && rm -rf /var/lib/apt/lists/* WORKDIR /app COPY --from=build /app/_build/prod/rel/hello_app ./ ENV PORT=8080 EXPOSE 8080 ENTRYPOINT ["/app/bin/hello_app", "foreground"] ``` Build and run with the same `docker build` / `docker run` commands as above, swapping the image name. ## Done 🎉 You can now commit and push the Dockerfile to your git repo. [Create a service](/environment/services/create) now to point at the git repository and branch name to deploy this image. To wire up Prometheus metrics for your Phoenix or Erlang service after deploying, see the [Erlang & Elixir instrumentation guide](/environment/services/instrument/erlang). If your nodes need to find each other over distributed Erlang — for Phoenix PubSub, a distributed registry, or handing work to a peer — see [BEAM clustering](/environment/services/beam-clustering). To form one cluster across environments in different regions, see [Cluster across regions](/environment/services/beam-clustering#cluster-across-regions). [elixir]: https://elixir-lang.org [erlang]: https://www.erlang.org [phoenix]: https://www.phoenixframework.org [phoenix-install]: https://hexdocs.pm/phoenix/installation.html [mix]: https://hexdocs.pm/mix/Mix.html [cowboy]: https://github.com/ninenines/cowboy [release]: https://hexdocs.pm/phoenix/releases.html [Docker]: https://www.docker.com/ # Go/gin Source: https://docs.localops.co/guides/languages/go In this guide we will set up a Dockerfile for your Go Application. ## Prerequisites To follow this tutorial, you will need the following: * [Go](https://go.dev/doc/install) * \[Docker] to build standalone containers to serve your Go app. > [!NOTE] > > This guide assumes that you have basic knowledge of the above-mentioned technologies and tools. If you are not > familiar with any of them, it is recommended to review their official documentation and tutorials to get up to speed > before proceeding with this guide. ## Go HTTP Server 1. Run the command `go mod init go-http-server` to set up your project and manage its dependencies. 2. Now, create a file named `main.go` and add the following code to set up a basic http server using the [gin](https://github.com/gin-gonic/gin) web framework. ```go main.go theme={null} package main import ( "log" "net/http" "github.com/gin-gonic/gin" ) func main() { router := gin.Default() router.GET("/", func(c *gin.Context) { c.JSON(http.StatusOK, gin.H{ "message": "Hello, World!", }) }) // Default port 8080 router.Run(":" + os.Getenv("APP_PORT")) } ``` 3. Export the required environment variables, ```shell theme={null} export APP_PORT=8080 ``` 4. Run `go mod download` command to download the required dependencies. 5. Run the command `go run main.go` to start the server. ## Dockerize Dockerizing makes your app run anywhere, agnostic of the platform. #### Create [.dockerignore](https://docs.docker.com/build/building/context/#dockerignore-files) Before creating the dockerfile, let's create a `.dockerignore` file and add that contents that should not be copied over to the docker file system. ```ignore .dockerignore theme={null} bin/ Dockerfile .dockerignore README.md .git ``` Read more about [.dockerignore here](https://docs.docker.com/build/building/context/#dockerignore-files) > [!NOTE] > > Creating a `.dockerinogre` file and adding folders like `node_modules` is must, since dependencies will be installed > while building the image based on the platform preferences used. Copying those from file system will overwrite the > installed dependencies and might fail during deployments #### Create Dockerfile Now, Create a [Dockerfile](https://docs.docker.com/reference/dockerfile/). The Dockerfile is a text file that contains the instructions for Docker to build the image. The Dockerfile is posted for reference with steps to create the production image. Though docker supports [Multi-Stage Builds](https://docs.docker.com/build/building/multi-stage/) we won't be using that here. In this example we will copy `source code` and build and run it inside the container. You can opt for multi stage build, if you want to build the go binary in build stage and run it in another stage. > [!TIP] > > Refer to this [doc](https://docs.docker.com/language/golang/build-images/) to know more about building docker images > for go applications. ```docker Dockerfile theme={null} # syntax=docker/dockerfile:1 FROM golang:1.21 # Set destination for COPY WORKDIR /app # Download Go modules COPY go.mod go.sum ./ RUN go mod download # Copy the source code. COPY *.go ./ # Build RUN GOOS=linux go build -o /go-http-server ./main.go # Optional: # To bind to a TCP port, runtime parameters must be supplied to the docker command. # But we can document in the Dockerfile what ports # the application is going to listen on by default. # https://docs.docker.com/reference/dockerfile/#expose EXPOSE 8080 # Run CMD ["/go-http-server"] ``` #### Build and test docker image Now you can build and run the Docker image. To build the Docker image: ```bash theme={null} docker build --platform linux/amd64 -t go-http-server . ``` This command builds the `go-http-server` image for platform `linux/amd64`. If you are locally testing your application, you can skip the `platform` key to build the images ```bash theme={null} # only for testing in local machine docker build -t go-http-server . ``` #### Run the docker image Let's run the Docker container using the image created of the react application with the command below. ```bash theme={null} docker run \ -it \ -p 8080:8080 \ --name go-http-server \ go-http-server ``` ## Done 🎉 You can now commit and push the Dockerfile to your git repo. [Create a service](/environment/services/create) now to point at the git repository and branch name to deploy this image. # Node/ExpressJS Source: https://docs.localops.co/guides/languages/node This documentation provides a step-by-step guide to setting up a Dockerfile for a HTTP server application written using [Express.js][express] and [Node.js][node]. ## Prerequisites To follow this tutorial, you will need the following: * [Node.js][node] (v20.15.1 at the time of writing this doc). * [npm] as a package manager for installing and maintaining dependencies. This usually comes bundled with Node.js. * A basic knowledge of [Node.js][node] and [Express.js][express]. * \[docker] to build standalone containers to serve your production app. > [!NOTE] > > This guide assumes that you have a basic knowledge of the above-mentioned technologies and tools. If you are not > familiar with any of them, it is highly recommended to review their official documentation and tutorials to get up to > speed before proceeding with this guide. ## Scaffolding the Node.js app Create a new folder for your Node.js project. In the following examples, we'll use the project name `node-project`. ```bash theme={null} mkdir cd ``` Use the [npm init](https://docs.npmjs.com/cli/commands/npm-init) command to create a `package.json` file for your application. For more information on how `package.json` works, see the specifics of [npm's package.json](https://docs.npmjs.com/cli/configuring-npm/package-json) handling. Run ```bash theme={null} npm init ``` and follow the prompts for various settings, such as the name (``) and version of your application. For now, you can simply hit RETURN to accept the defaults for most of them, with the following exception: ```sh theme={null} entry point: (index.js) ``` Enter `app.js`, or whatever you want the name of the main file to be. If you want it to be `index.js`, hit RETURN to accept the suggested default file name. ### Installing Express.js At this point, you have a Node.js project ready. Let's install Express and save it in the dependency list by running ```bash theme={null} npm install express ``` > [!NOTE] > > At the time of writing this guide, the latest `express` version is 4.19.2. If you have more questions, check out the [Node.js guide](https://nodejs.org/en/learn/getting-started/introduction-to-nodejs) and [Express.js guide](https://expressjs.com/en/starter/installing.html) to learn more about scaffolding the app. You can also use tools like [express-generator](https://expressjs.com/en/starter/generator.html) to quickly scaffold your app. Note: While writing this guide, the express-generator is not very well maintained and has known issues with tools provided out of the box; hence, it is recommended to use a manual setup, which is also straightforward. ### Hello World! example Create a file called `app.js` as mentioned earlier for the entry point and write a simple Express app that returns `Hello World!` when navigating to the `/` path of the URL. ```js app.js theme={null} const express = require('express'); // import the express dependency const app = express(); // create the app // Look for port from the environment variables. // or use the fallback port const port = process.env.PORT ?? 3500; // Create a route to handle `/` and return `Hello World!` in the response. app.get('/', (req, res) => { res.send('Hello World!'); }); // Start the HTTP router on the given port. app.listen(port, () => { console.log(`Example app listening on port ${port}`); }); // Handle the exit signal and quit the process. process.on('SIGINT', function () { process.exit(); }); ``` All of your dependencies should be installed at this point (which you can verify by checking for the existence of a `node_modules` folder in your project), so you can start your project by running the command: ```bash theme={null} node app.js ``` If everything is successful, you should see a similar confirmation message in your terminal: ``` Example app listening on port 3500 ``` Open `http://localhost:3500` in your browser of choice. You should see the Node.js app running and printing `Hello World!` in the document. ## Create the Docker image Dockerizing makes the app run anywhere, agnostic of the platform. As long as Docker is installed, whether it's Windows, Mac, or Linux, it can run with the same behavior. Before creating the Dockerfile, let's create a `.dockerignore` file and add the contents that should not be copied over to the Docker file system. ```ignore .dockerignore theme={null} Dockerfile .dockerignore node_modules npm-debug.log README.md .git ``` Read more about [.dockerignore here](https://docs.docker.com/build/building/context/#dockerignore-files). > [!NOTE] > > Creating a `.dockerignore` file and adding folders like `node_modules` is a must since dependencies will be installed > while building the image based on the platform preferences used. Copying those from the file system will overwrite the > installed dependencies and might error out during deployment. Now, create a [Dockerfile](https://docs.docker.com/reference/dockerfile/). The Dockerfile is a text file that contains the instructions for Docker to build the image. The Dockerfile is posted for reference with steps to create the production image. Though Docker supports [Multi-Stage Builds](https://docs.docker.com/build/building/multi-stage/), we won't be using that here since Node.js needs all the `source code` and `node_modules` to be present while running the application. You can opt for multi-stage builds if your process fits that approach. ```docker Dockerfile theme={null} # Use nodejs v20 alpine image FROM node:20-alpine # Switch to the app directory, # This will be our app's root directory inside the container. WORKDIR /app # Copy the manifest and lock file to the root. # Note: ./ refers to /app, since we switched context in the above step. COPY package.json package-lock.json* ./ # Set the NODE_ENV to production. # to configure the application to build/run under production mode # this also tells npm to not install devDependencies mentioned in package.json # as we won't be needing that to run our app ENV NODE_ENV=production # Install the production dependencies RUN npm ci # Copy all the files from our machine to the container COPY . . # The port you'd like to use for Nginx ENV PORT=3500 # Expose the port the Nginx is running to the outside world EXPOSE ${PORT} # Start the node server ENTRYPOINT ["node","./app.js"] ``` Now you can build and run the Docker image. To build the Docker image: ```bash theme={null} docker build --platform linux/amd64 -t node-app:latest . ``` This command builds the `node-app` image for platform `linux/amd64` and tags it as `latest`. If you are locally testing your application, you can skip the `platform` key to build the images ```bash theme={null} # only for testing on local machine docker build -t node-app:latest . ``` ## Run the Docker image Let's run the Docker container using the image created of the Node application with the command below. ```bash theme={null} docker run \ -it \ --rm \ --name node-app \ -e PORT=3500 \ -d \ -p 3500:3500 \ node-app ``` * `-it`: enables interactivity with TTY. * `--rm`: tells the Docker Daemon to clean up the container and remove the file system after the container exits. * `--name node-app`: Name of the container `node-app`. * `-e PORT=3500`: Sets the environment variable PORT in Docker to `3500`. * `-d`: Runs the container in detached (background) mode. You can skip the flag to see the logs directly in your terminal window. * `-p 3500:3500`: Maps port 3500 on your host to port 3500 in the container. * `node-app` at the end is the name of the image. After running the command, visit `http://localhost:3500` to see the Node.js application running inside the Docker container. Hurray! Now we have created and packaged a Node app for production use. ## Done 🎉 You can now commit and push the Dockerfile to your git repo. [Create a service](/environment/services/create) now to point at the git repository and branch name to deploy this image. [node]: https://nodejs.org/en [npm]: https://www.npmjs.com [express]: https://expressjs.com # Python/Django Source: https://docs.localops.co/guides/languages/python This documentation provides a step-by-step guide to setting up a Python Django server and creating a Dockerfile to deploy it via LocalOps. ## Prerequisites To follow this tutorial, you will need the following: * [Python](https://www.python.org/downloads) - v3.12.4 at the time of writing this doc. * [pip](https://packaging.python.org/en/latest/tutorials/installing-packages) as a package manager for installing and maintaining dependencies. This usually comes bundled with Python > v3.4. * [Django](https://djangoproject.com) - v5.0.7 at the time of writing this doc. * \[Docker] to build standalone containers to serve your Python app. > [!NOTE] > > This guide assumes that you have basic knowledge of the above-mentioned technologies and tools. If you are not > familiar with any of them, it is recommended to review their official documentation and tutorials to get up to speed > before proceeding with this guide. ## Example Python Django App In this tutorial we can go over a simple to-do app that was created using Python Django. Source Code: [https://github.com/localopsco/django-todo-example](https://github.com/localopsco/django-todo-example) ## Create Python Django app > [!TIP] > > You can also follow [Django documentation](https://docs.djangoproject.com) to create a simple Django app. #### Use python venv (Virtual Environment) ```shell theme={null} python3 -m venv ~/.virtualenvs/djangodev source ~/.virtualenvs/djangodev/bin/activate ``` #### Install `Django` using `pip` ```shell theme={null} pip install Django ``` #### Start a Django project ```shell theme={null} django-admin startproject django_todo ``` #### Start a Django app in the project ```shell theme={null} python manage.py startapp todo ``` ### Connect to your DB > [!TIP] > > Please refer [this Django article](https://docs.djangoproject.com/en/5.0/ref/settings/#databases) to connect to your > Database. In the tutorial example we will be connecting to Postgres DB. Update your project `settings.py` file to refer the database details from environment variables. ```python django_todo/settings.py theme={null} DATABASES = { 'default': { 'ENGINE': 'django.db.backends.postgresql', 'NAME': os.environ.get('DB_NAME'), 'USER': os.environ.get('DB_USER'), 'PASSWORD': os.environ.get('DB_PASS'), 'HOST': os.environ.get('DB_HOST'), 'PORT': os.environ.get('DB_PORT'), } } ``` Make sure you have already created the provided database with username and password. ### Create DB models > [!TIP] > > You can refer [this Django model article](https://docs.djangoproject.com/en/5.0/topics/db/models) to know more on > creating DB models. * Update the `todo/models.py` file with below content, ```python todo/models.py theme={null} from django.db import models import uuid class Task(models.Model): id = models.UUIDField(primary_key=True, default=uuid.uuid4, editable=False) title = models.CharField(max_length=255) description = models.TextField() is_completed = models.BooleanField(default=False) attachment_url = models.URLField(null=True, blank=True) created_at = models.DateTimeField(auto_now_add=True) def __str__(self): return self.title ``` #### Apply migrations ```shell theme={null} python manage.py migrate ``` ### Add API endpoints > [!TIP] > > You can use [Django REST Framework](https://www.django-rest-framework.org) package to quickly bootstrap REST > endpoints. In this tutorial we will be adding REST CRUD (Create, Read, Update and Delete) endpoints for `Task` model using [Django REST Framework](https://www.django-rest-framework.org). Copy paste the below contents to your respective files, ```python todo/views.py theme={null} from rest_framework import viewsets from .models import Task from .serializers import TaskSerializer class TaskViewSet(viewsets.ModelViewSet): queryset = Task.objects.all() serializer_class = TaskSerializer def create(self, request, *args, **kwargs): return super().create(request, *args, **kwargs) def update(self, request, *args, **kwargs): return super().update(request, *args, **kwargs) def retrieve(self, request, *args, **kwargs): return super().retrieve(request, *args, **kwargs) def list(self, request, *args, **kwargs): return super().list(request, *args, **kwargs) def destroy(self, request, *args, **kwargs): return super().destroy(request, *args, **kwargs) ``` ```python todo/urls.py theme={null} from django.urls import path, include from rest_framework.routers import DefaultRouter from .views import TaskViewSet router = DefaultRouter() router.register(r'tasks', TaskViewSet, basename='task') urlpatterns = [ path('', include(router.urls)), ] ``` ```python django_todo/urls.py theme={null} from django.contrib import admin from django.urls import path, include urlpatterns = [ path('admin/', admin.site.urls), path('api/v1/', include('todo.urls')), ] ``` ### Run server Export the required environment variables, ```shell theme={null} export DB_NAME=djangotodo \ DB_USER=localops \ DB_PASS=localops \ DB_HOST=localhost \ DB_PORT=5432 ``` Run Django server, ```shell theme={null} python ./manage.py runserver ``` Visit `http://localhost:8000/api/v1/tasks/` to see the list of tasks served from our Django app. **Voila! You have successfully created and run **Django Python server** with REST CRUD endpoints for Task model. 🎉** ## Dockerize Dockerizing makes the app run anywhere, agnostic of the platform. As long as Docker is installed, whether it's Windows, Mac, or Linux, it can run with the same behavior. ### Create [.dockerignore](https://docs.docker.com/build/building/context/#dockerignore-files) Before creating the dockerfile, let's create a `.dockerignore` file and add that contents that should not be copied over to the docker file system. ```ignore .dockerignore theme={null} __pycache__/ Dockerfile .dockerignore README.md .git ``` Read more about [.dockerignore here](https://docs.docker.com/build/building/context/#dockerignore-files) > [!NOTE] > > Creating a `.dockerignore` file and adding folders like `node_modules` is must, since dependencies will be installed > while building the image based on the platform preferences used. Copying those from file system will overwrite the > installed dependencies and might fail during deployment ### Run DB migration inside docker image In this tutorial, to keep DB migration step simple, we will create a `entrypoint.sh` script to run DB migrations each time the docker image is run. ```shell entrypoint.sh theme={null} #!/bin/bash set -e # Apply migrations python manage.py migrate # Start the Django application exec "$@" ``` Optionally you can have a separate image to run your DB migrations. In production setup, it is advisable to have separate image to run DB migrations. ### Create [Dockerfile](https://docs.docker.com/reference/dockerfile/) Now, Create a [Dockerfile](https://docs.docker.com/reference/dockerfile/). The Dockerfile is a text file that contains the instructions for Docker to build the image. The Dockerfile is posted for reference with steps to create the production image. Though docker supports [Multi-Stage Builds](https://docs.docker.com/build/building/multi-stage/) we won't be using that here since Python needs all the `source code` and dependencies to be present while running the application. You can opt for multi stage build, if you have any build tool. ```docker Dockerfile theme={null} # Use an official Python runtime as a parent image FROM python:3.12-alpine # Set environment variables ENV PYTHONDONTWRITEBYTECODE 1 ENV PYTHONUNBUFFERED 1 # Create and set the working directory WORKDIR /app # Copy the requirements file into the container COPY requirements.txt /app/ # Install utils RUN apk update RUN apk upgrade RUN apk add bash RUN apk add \ build-base \ gcc \ libc-dev \ linux-headers \ python3-dev \ musl-dev \ libffi-dev # Use the custom entrypoint script COPY entrypoint.sh /app/entrypoint.sh RUN chmod +x /app/entrypoint.sh ENTRYPOINT ["/app/entrypoint.sh"] # Install the project dependencies RUN pip install -r requirements.txt # Copy the rest of the application code into the container COPY . /app/ # Expose the port the app runs on EXPOSE 8000 # Start the application CMD ["python", "manage.py", "runserver", "0.0.0.0:8000"] ``` ### Build docker image Now you can build and run the Docker image. To build the Docker image: ```bash theme={null} docker build --platform linux/amd64 -t django-todo . ``` This command builds the `django-todo` image for platform `linux/amd64`. If you are locally testing your application, you can skip the `platform` key to build the images ```bash theme={null} # only for testing in local machine docker build -t django-todo . ``` ### Run the docker image Let's run the Docker container using the image created of the react application with the command below. ```bash theme={null} docker run \ -it \ -p 8000:8000 \ -e DB_HOST=localhost \ -e DB_PORT=5432 \ -e DB_NAME=djangotodo \ -e DB_USER=localops \ -e DB_PASS=localops \ --name django-todo \ django-todo ``` This command requires PostgresDB to be running on `localhost:54321`. ### Docker Compose If you want to run PostgresDB alongside our Django image, then we can create a `docker-compose.yml` file with below content, ```yaml docker-compose.yml theme={null} version: '3' volumes: pg_data_todo: services: be: build: . environment: DB_HOST: db DB_NAME: todo_db DB_USER: todo_user DB_PASS: todo_pass REDIS_HOST: redis S3_REGION: ap-south-1 AWS_ACCESS_KEY_ID: XYZ AWS_SECRET_ACCESS_KEY: XYZ S3_BUCKET_NAME: test-bucket ports: - '8000:8000' depends_on: - db db: image: postgres:14.8-alpine3.18 environment: POSTGRES_DB: todo_db POSTGRES_USER: todo_user POSTGRES_PASSWORD: todo_pass volumes: - pg_data_todo:/var/lib/postgresql/data ports: - '5432:5432' ``` #### Docker compose up ```shell theme={null} docker compose up ``` After running the command, Visit `http://localhost:8000/api/v1/tasks/` to list the tasks. Hurray 🎉. Now we have created and Dockerized a Python Django app. ### Deploy You can now commit and push the Dockerfile to your git repo. [Create a service](/environment/services/create) now to point at the git repository and branch name to deploy this image. # Angular Source: https://docs.localops.co/guides/spa/angular This documentation provides a step-by-step guide to prepare a Single Page Application (SPA) that was built using Angular for deploying it in any cloud using LocalOps. ## Prerequisites To follow this tutorial, you will need the following: * [Node.js][node], v20.15.1 at the time of writing this doc. * [npm] as a package manager for installing and maintaining dependencies. This usually comes bundled with Node.js. * A foundational knowledge of [Angular]. * [Angular CLI](https://angular.dev/cli) for a development server and building optimized static assets for production. * [Nginx] to serve static assets and also act as a reverse proxy server. * [Docker] to build standalone containers to serve your production app. > [!NOTE] > > This guide assumes that you have basic knowledge of the above-mentioned technologies and tools. If you are not > familiar with any of them, it is highly recommended to review their official documentation and tutorials to get up to > speed before proceeding with this guide. ## Installing the Angular CLI You'll need to install the Angular CLI to scaffold a new project. Open a terminal and run the following command: ```bash theme={null} npm install -g @angular/cli ``` If you are having issues running this command in Windows or Unix, check out the [CLI docs](https://angular.dev/tools/cli/setup-local#install-the-angular-cli) for more info. ## Scaffolding the Angular app In your terminal, run the CLI command `ng new` with the desired project name. In the following examples, we'll be using the example project name of `angular-project`. ```bash theme={null} ng new ``` Follow the prompts to create your first app. When prompted with the question `Do you want to enable Server-Side Rendering (SSR) and Static Site Generation?`, proceed with `N` (no), since this guide focuses only on single-page applications. We'll cover SSR in another guide. If you have more questions, check out the [Angular installation guide](https://angular.dev/installation) to learn more about scaffolding the app. Once the application is ready, navigate to the directory and install all the dependencies: ```bash theme={null} cd angular-project # replace with the name of the project you created ``` All of your dependencies should be installed at this point (which you can verify by checking for the existence of a `node_modules` folder in your project), so you can start your project by running the command: ```bash theme={null} npm start ``` If everything is successful, you should see a similar confirmation message in your terminal: ``` Watch mode enabled. Watching for file changes... NOTE: Raw file sizes do not reflect development server per-request transformations. ➜ Local: http://localhost:4200/ ➜ press h + enter to show help ``` Now you can visit the path in Local (e.g., `http://localhost:4200`) to see your application. ## Building Your Production App When it is time to deploy your app for production, simply run: ```bash theme={null} npm run build ``` This will compile your TypeScript code to JavaScript, as well as optimize, bundle, and minify the output as appropriate. The result of this build process is output to a directory (`dist/${PROJECT_NAME}` by default). ### Configuring nginx Once the application is built for production, we need a static web server to serve those files. For that purpose, we are using \[Nginx]. Nginx is an open-source HTTP and reverse proxy server. ```nginx nginx.conf.template theme={null} server { listen ${PORT}; server_name _; location / { root /usr/share/nginx/html; try_files $uri $uri/ /index.html; } # skip this block if you don't have a backend yet location /api/ { proxy_pass http://{BACKEND_HOST}:${BACKEND_PORT}; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } error_page 500 502 503 504 /50x.html; location = /50x.html { root /usr/share/nginx/html; } } ``` Create this file `nginx.conf.template` in the root of your project. We won't be using this template now; we'll use it to run the Nginx server inside the Docker container. Note two important blocks in this configuration: ```nginx theme={null} location / { root /usr/share/nginx/html; try_files $uri $uri/ /index.html; } ``` This block serves the `index.html` from the files we built using Ember, stored in the `/usr/share/nginx/html` folder. We will copy the assets to this folder while building the Docker application. And then the API block: ```nginx theme={null} location /api/ { proxy_pass http://{BACKEND_HOST}:${BACKEND_PORT}; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } ``` > [!NOTE] > > You might want to skip the API block if you don't have a backend yet; otherwise, nginx will throw an error for an > invalid host on the backend URL. A typical non-static web application usually will have a backend, and we make AJAX requests using [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) or libraries like [axios](https://axios-http.com/docs/intro) to get/send data to retrieve/store the application state. Assume that the site we built is being served by nginx via the domain `example.com`. Whenever an API call is made to `example.com/api`, the nginx server acts as a reverse proxy server and forwards the request to the backend server. You can use reverse proxying to navigate the traffic that is inbound to nginx. The reverse proxy server also acts as a mask, hiding the real backend from the outside world. ### Create the Docker Image Dockerizing makes the app run anywhere, agnostic of the platform. As long as Docker is installed, whether it's Windows, Mac, or Linux, it can run with the same behavior. Before creating the Dockerfile, let's create a `.dockerignore` file and add the contents that should not be copied over to the Docker file system. ```ignore .dockerignore theme={null} Dockerfile .dockerignore node_modules npm-debug.log README.md .git ``` Read more about [.dockerignore here](https://docs.docker.com/build/building/context/#dockerignore-files). > [!NOTE] > > Creating a `.dockerignore` file and adding folders like `node_modules` is a must, since dependencies will be installed > while building the image based on the platform preferences used. Copying those from the file system will overwrite the > installed dependencies and might cause errors during deployment. Now, create a [Dockerfile](https://docs.docker.com/reference/dockerfile/). The Dockerfile is a text file that contains the instructions for Docker to build the image. The Dockerfile is posted for reference with steps to create the production image. We leverage Docker's [Multi-Stage Builds](https://docs.docker.com/build/building/multi-stage/) to create a smaller-sized image for running the production server. ```docker Dockerfile theme={null} # Stage 1: Base # This stage is the first stage FROM node:20-alpine AS base # Switch to the app directory, # this will be our app's root directory inside the container WORKDIR /app # Copy the manifest and lock file to the root # Note: ./ refers to /app, since we switched context in the above step COPY package.json package-lock.json* ./ # Install the dependencies RUN npm ci # Set the NODE_ENV to production # to configure the application to build/run under production mode ENV NODE_ENV=production # Copy all the files from our machine to the container COPY . . # Run the build to create production assets RUN npm run build # Stage 2: Production # Now we build a new stage from scratch to run the nginx server # This won't include any images from the previous steps FROM nginx:alpine AS production # The port you'd like to use for Nginx ENV PORT=4200 # The URL for the backend service ENV BACKEND_HOST=host.docker.internal # Port for the backend ENV BACKEND_PORT=4500 # Copy the template we created earlier for nginx to the etc folder # note the destination file name should be default.conf.template # else the variables in the config won't work COPY nginx.conf.template /etc/nginx/templates/default.conf.template # Since we started a new stage, we need to copy the build from the # build step to the nginx's html directory. Note we have configured # this directory in the nginx config file COPY --from=base /app/dist/angular-project/browser /usr/share/nginx/html # Expose the port the nginx is running to the outside world EXPOSE ${PORT} # Start the nginx server CMD ["nginx", "-g", "daemon off;"] ``` Now you can build and run the Docker image. To build the Docker image: ```bash theme={null} docker build --platform linux/amd64 -t angular-app:latest . ``` This command builds the `angular-app` image for platform `linux/amd64` and tags it as `latest`. If you are locally testing your application, you can skip the `platform` key to build the images: ```bash theme={null} # only for testing in local machine docker build -t angular-app:latest . ``` ### Run the Docker Image Let's run the Docker container using the image created of the Angular application with the command below. ```bash theme={null} docker run \ -it \ --rm \ --name angular-app \ -e PORT=4200 \ -e BACKEND_PORT=4500 \ -e BACKEND_HOST=host.docker.internal \ -d \ -p 4200:4200 \ angular-app ``` * `-it`: Enables interactivity with TTY. * `--rm`: Tells the Docker Daemon to clean up the container and remove the file system after the container exits. * `--name angular-app`: Names the container `angular-app`. * `-e PORT=4200`: Sets the environment variable PORT in Docker to `4200`. * `-e BACKEND_PORT=4500`: Sets the environment variable BACKEND\_PORT in Docker to `4500`. * `-e BACKEND_HOST=host.docker.internal`: Sets the environment variable BACKEND\_HOST in Docker to `host.docker.internal`. * `-d`: Runs the container in detached (background) mode. You can skip this flag to see the logs directly in your terminal window. * `-p 4200:4200`: Maps port 4200 on your host to port 4200 in the container. * `angular-app`: The name of the image. After running the command, visit `http://localhost:4200` to see the Angular application running inside the Docker container. Hurray 🎉. Now we have created and packaged an Angular app for production use. ## Done 🎉 You can now commit and push the Dockerfile to your git repo. [Create a service](/environment/services/create) now to point at the git repository and branch name to deploy this image. [angular]: https://angular.dev/ [npm]: https://docs.npmjs.com/about-npm [node]: https://nodejs.org/en [docker]: https://docs.docker.com/ [nginx]: https://nginx.org/en/ # Ember Source: https://docs.localops.co/guides/spa/ember This documentation provides a step-by-step guide to prepare a Single Page Application (SPA) that was built using Ember.js for deploying it in any cloud using LocalOps. ## Prerequisites To follow this tutorial, you will need the following: * [Node.js][node], v20.15.1 at the time of writing this doc. * [npm] as a package manager for installing and maintaining dependencies. This usually comes bundled with Node.js. * A foundational knowledge of [Ember.js][ember]. * [Nginx] to serve static assets and also act as a reverse proxy server. * [Docker] to build standalone containers to serve your production app. > [!NOTE] > > This guide assumes that you have basic knowledge of the above-mentioned technologies and tools. If you are not > familiar with any of them, it is highly recommended to review their official documentation and tutorials to get up to > speed before proceeding with this guide. ## Installing the Ember CLI You'll need to install Ember CLI to scaffold a new project. Open a terminal and run the following command: ```bash theme={null} npm install -g ember-cli ``` Check out the [Ember CLI docs](https://cli.emberjs.com/release/) for more info. ## Scaffolding the Ember app In your terminal, run the CLI command `ember new` with the desired project name. In the following examples, we'll use the example project name `ember-project`. ```bash theme={null} ember new --lang en ``` Follow the prompts to create your first app. If you have more questions, check out the [Quickstart guide](https://guides.emberjs.com/release/getting-started/quick-start/) to learn more about scaffolding the app. Once the application is ready, navigate to the directory and install all the dependencies: ```bash theme={null} cd ember-project # replace with the name of the project you created ``` All of your dependencies should be installed at this point (which you can verify by checking for the existence of a `node_modules` folder in your project). You can start your project by running the command: ```bash theme={null} npm start ``` If everything is successful, you should see a similar confirmation message in your terminal: ``` Livereload server on http://localhost:7020 Serving on http://localhost:4200/ ``` Open `http://localhost:4200` in your browser of choice. You should see an Ember welcome page and not much else. > [!NOTE] > > Replace the `` component in `/app/templates/application.hbs` before building for > production with your app logic or something else to avoid errors while starting the application. ## Building Your Production App Now that we've written our application and verified that it works in development, it's time to get it ready to deploy to our users. ```bash theme={null} npm run build ``` The `build` command packages up all of the assets that make up your application—JavaScript, templates, CSS, web fonts, images, and more—in an optimized way for production use. ### Configuring nginx Once the application is built for production, we need a static web server to serve those files. For that purpose, we are using \[Nginx]. Nginx is an open-source HTTP and reverse proxy server. ```nginx nginx.conf.template theme={null} server { listen ${PORT}; server_name _; location / { root /usr/share/nginx/html; try_files $uri $uri/ /index.html; } # skip this block if you don't have a backend yet location /api/ { proxy_pass http://{BACKEND_HOST}:${BACKEND_PORT}; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } error_page 500 502 503 504 /50x.html; location = /50x.html { root /usr/share/nginx/html; } } ``` Create this file `nginx.conf.template` in the root of your project. We won't be using this template now; we'll use it to run the Nginx server inside the Docker container. Note two important blocks in this configuration: ```nginx theme={null} location / { root /usr/share/nginx/html; try_files $uri $uri/ /index.html; } ``` This block serves the `index.html` from the files we built using Ember, stored in the `/usr/share/nginx/html` folder. We will copy the assets to this folder while building the Docker application. And then the API block: ```nginx theme={null} location /api/ { proxy_pass http://{BACKEND_HOST}:${BACKEND_PORT}; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } ``` > [!NOTE] > > You might want to skip the API block if you don't have a backend yet; otherwise, nginx will throw an error for an > invalid host on the backend URL. A typical non-static web application usually will have a backend, and we make AJAX requests using [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) or libraries like [axios](https://axios-http.com/docs/intro) to get/send data to retrieve/store the application state. Assume that the site we built is being served by nginx via the domain `example.com`. Whenever an API call is made to `example.com/api`, the nginx server acts as a reverse proxy server and forwards the request to the backend server. You can use reverse proxying to navigate the traffic that is inbound to nginx. The reverse proxy server also acts as a mask, hiding the real backend from the outside world. ### Create the Docker Image Dockerizing makes the app run anywhere, agnostic of the platform. As long as Docker is installed, whether it's Windows, Mac, or Linux, it can run with the same behavior. Before creating the Dockerfile, let's create a `.dockerignore` file and add the contents that should not be copied over to the Docker file system. ```ignore .dockerignore theme={null} Dockerfile .dockerignore node_modules npm-debug.log README.md .git ``` Read more about [.dockerignore here](https://docs.docker.com/build/building/context/#dockerignore-files). > [!NOTE] > > Creating a `.dockerignore` file and adding folders like `node_modules` is a must since dependencies will be installed > while building the image based on the platform preferences used. Copying those from the file system will overwrite the > installed dependencies and might error out during deployment. Now, create a [Dockerfile](https://docs.docker.com/reference/dockerfile/). The Dockerfile is a text file that contains the instructions for Docker to build the image. The Dockerfile is posted for reference with steps to create the production image. We leverage Docker's [Multi-Stage Builds](https://docs.docker.com/build/building/multi-stage/) to create a smaller-sized image for running the production server. ```docker Dockerfile theme={null} # Stage 1: Base # This stage is the first stage FROM node:20-alpine AS base # Switch to the app directory, # this will be our app's root directory inside the container WORKDIR /app # Copy the manifest and lock file to the root # Note: ./ refers to /app, since we switched context in the above step COPY package.json package-lock.json* ./ # Install the dependencies RUN npm ci # Set the NODE_ENV to production # to configure the application to build/run under production mode ENV NODE_ENV=production # Copy all the files from our machine to the container COPY . . # Run the build to create production assets RUN npm run build # Stage 2: Production # Now we build a new stage from scratch to run the nginx server # This won't include any images from the previous steps FROM nginx:alpine AS production # The port you'd like to use for Nginx ENV PORT=4200 # The URL for the backend service ENV BACKEND_HOST=host.docker.internal # Port for the backend ENV BACKEND_PORT=4500 # Copy the template we created earlier for nginx to the etc folder # note the destination file name should be default.conf.template # else the variables in the config won't work COPY nginx.conf.template /etc/nginx/templates/default.conf.template # Since we started a new stage, we need to copy the build from the # build step to the nginx's html directory. Note we have configured # this directory in the nginx config file COPY --from=base /app/dist /usr/share/nginx/html # Expose the port the nginx is running to the outside world EXPOSE ${PORT} # Start the nginx server CMD ["nginx", "-g", "daemon off;"] ``` Now you can build and run the Docker image. To build the Docker image: ```bash theme={null} docker build --platform linux/amd64 -t ember-app:latest . ``` This command builds the `ember-app` image for platform `linux/amd64` and tags it as `latest`. If you are locally testing your application, you can skip the `platform` key to build the images: ```bash theme={null} # only for testing on the local machine docker build -t ember-app:latest . ``` ### Run the Docker Image Let's run the Docker container using the image created for the Ember application with the command below. ```bash theme={null} docker run \ -it \ --rm \ --name ember-app \ -e PORT=4200 \ -e BACKEND_PORT=4500 \ -e BACKEND_HOST=host.docker.internal \ -d \ -p 4200:4200 \ ember-app ``` * `-it`: enables interactivity with TTY * `--rm`: tells the Docker Daemon to clean up the container and remove the file system after the container exits * `--name ember-app`: Name of the container `ember-app`. * `-e PORT=4200`: Sets the environment variable PORT in Docker to `4200`. * `-e BACKEND_PORT=4500`: Sets the environment variable BACKEND\_PORT in Docker to `4500`. * `-e BACKEND_HOST=host.docker.internal`: Sets the environment variable BACKEND\_HOST in Docker to `host.docker.internal`. * `-d`: Runs the container in detached (background) mode. You can skip the flag to see the logs directly in your terminal window. * `-p 4200:4200`: Maps port 4200 on your host to port 4200 in the container. * `ember-app` at the end is the name of the image. The `-d` flag in Docker starts the container in the background. You can skip the flag to see the logs directly in your terminal window. After running the command, visit `http://localhost:4200` to see the Ember application running inside the Docker container. Hurray 🎉. Now we have created and packaged an Ember app for production use. ## Done 🎉 You can now commit and push the Dockerfile to your git repo. [Create a service](/environment/services/create) now to point at the git repository and branch name to deploy this image. [ember]: https://guides.emberjs.com/release/ [npm]: https://docs.npmjs.com/about-npm [node]: https://nodejs.org/en [docker]: https://docs.docker.com/ [nginx]: https://nginx.org/en/ # Next.js Source: https://docs.localops.co/guides/spa/nextjs This documentation provides a step-by-step guide to prepare a Next.js app and dockerizing it for deploying it to any cloud using LocalOps. ## Prerequisites To follow this tutorial, you will need the following: * [Node.js][node], version 18.x or later at the time of writing. * [npm], as a package manager for installing and maintaining dependencies. This usually comes bundled with Node.js. * A foundational knowledge of [Next.js][next]. * [Docker] to build standalone containers to serve your production app. > [!NOTE] > > This guide assumes that you have basic knowledge of the above-mentioned technologies and tools. If you are not > familiar with any of them, it is recommended to review their official documentation and tutorials to get up to speed > before proceeding with this guide. ## Scaffolding the Next.js app Next.js offers a CLI tool to quickly scaffold a new project. Run the following command: ```bash theme={null} npx create-next-app@latest ``` Follow the prompts to create your app. Refer to the [Next.js Getting Started guide](https://nextjs.org/docs/getting-started) to learn more about scaffolding the app. Once the application is ready, navigate to the directory and install all the dependencies (if not already installed): ```bash theme={null} cd your-nextjs-app # replace with the name of the project you created npm install ``` Once the dependencies are installed, you can start the dev server by running: ```bash theme={null} npm run dev ``` This usually starts the server on port `3000`. Go to [http://localhost:3000](http://localhost:3000) to see your app. The dev server supports hot reloading, so it reloads the application when you make changes. ## Building and Dockerizing a Next.js App When it is time to deploy your app for production, simply run: ```bash theme={null} npm run build ``` This command builds an optimized production bundle. The output is found in the `.next` directory. > [!TIP] > > Once built, you can preview the production build using `npm run start` to start a local production server. ### Create the Docker Image Below is a Dockerfile optimized for Next.js, using multi-stage builds for smaller images and best practices for dependency management. ```docker Dockerfile theme={null} # syntax=docker.io/docker/dockerfile:1 FROM node:18-alpine AS base # Install dependencies only when needed FROM base AS deps # Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed. RUN apk add --no-cache libc6-compat WORKDIR /app # Install dependencies based on the preferred package manager COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* .npmrc* ./ RUN \ if [ -f yarn.lock ]; then yarn --frozen-lockfile; \ elif [ -f package-lock.json ]; then npm ci; \ elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \ else echo "Lockfile not found." && exit 1; \ fi # Rebuild the source code only when needed FROM base AS builder WORKDIR /app COPY --from=deps /app/node_modules ./node_modules COPY . . # Next.js collects completely anonymous telemetry data about general usage. # Learn more here: https://nextjs.org/telemetry # Uncomment the following line in case you want to disable telemetry during the build. # ENV NEXT_TELEMETRY_DISABLED=1 RUN \ if [ -f yarn.lock ]; then yarn run build; \ elif [ -f package-lock.json ]; then npm run build; \ elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; \ else echo "Lockfile not found." && exit 1; \ fi # Production image, copy all the files and run next FROM base AS runner WORKDIR /app ENV NODE_ENV=production # Uncomment the following line in case you want to disable telemetry during runtime. # ENV NEXT_TELEMETRY_DISABLED=1 RUN addgroup --system --gid 1001 nodejs RUN adduser --system --uid 1001 nextjs COPY --from=builder /app/public ./public # Automatically leverage output traces to reduce image size # https://nextjs.org/docs/advanced-features/output-file-tracing COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./ COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static USER nextjs EXPOSE 3000 ENV PORT=3000 # server.js is created by next build from the standalone output # https://nextjs.org/docs/pages/api-reference/config/next-config-js/output ENV HOSTNAME="0.0.0.0" CMD ["node", "server.js"] ``` Now you can build and run the Docker image. To build the Docker image: ```bash theme={null} docker build --platform linux/amd64 -t nextjs-app:latest . ``` This command builds the `nextjs-app` image for the platform `linux/amd64` and tags it as `latest`. If you are locally testing your application, you can skip the `platform` key to build the images. ```bash theme={null} # only for testing in a local machine docker build -t nextjs-app:latest . ``` ### Run the Docker Image Let's run the Docker container using the image created of the Next.js application with the command below. ```bash theme={null} docker run \ -it \ --rm \ --name nextjs-app \ -e PORT=3000 \ -d \ -p 3000:3000 \ nextjs-app ``` * `-it`: enables interactivity with TTY. * `--rm`: tells the Docker Daemon to clean up the container and remove the file system after the container exits. * `--name nextjs-app`: Name of the container `nextjs-app`. * `-e PORT=3000`: Sets the environment variable PORT in Docker to `3000`. * `-d`: Runs the container in detached (background) mode. You can skip the flag to see the logs directly in your terminal window. * `-p 3000:3000`: Maps port 3000 on your host to port 3000 in the container. * `nextjs-app` at the end is the name of the image. After running the command, visit `http://localhost:3000` to see the Next.js application running inside the Docker container. Hurray 🎉. Now we have created and packaged a Next.js app for production use. ## Example app ```text theme={null} Source: https://github.com/vercel/next.js/tree/canary/examples/with-docker ``` You can refer to the `with-docker` example, which is an official example published by the Next.js team. ## Done 🎉 You can now commit and push the Dockerfile to your git repo. [Create a service](/environment/services/create) to point at the git repository and branch name to deploy this image. [next]: https://nextjs.org/ [node]: https://nodejs.org/en [npm]: https://docs.npmjs.com/about-npm [docker]: https://docs.docker.com/ # ReactJS Source: https://docs.localops.co/guides/spa/react This documentation provides a step-by-step guide to prepare a Single Page Application (SPA) that was built using ReactJS for deploying it in any cloud using LocalOps. ## Prerequisites To follow this tutorial, you will need the following: * [Node.js][node], version 20.15.1 at the time of writing. * [npm], as a package manager for installing and maintaining dependencies. This usually comes bundled with Node.js. * A foundational knowledge of [React]. * [Vite] for a development server and building optimized static assets for production. * [Nginx] to serve static assets and also act as a reverse proxy server. * [Docker] to build standalone containers to serve your production app. > [!NOTE] > > This guide assumes that you have basic knowledge of the above-mentioned technologies and tools. If you are not > familiar with any of them, it is recommended to review their official documentation and tutorials to get up to speed > before proceeding with this guide. ## Scaffolding the React app Vite offers a CLI tool that makes the scaffolding process much easier. Run the following command: ```bash theme={null} npm create vite@latest ``` Follow the prompts to create your first app. Refer to the [Vite guide](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) to learn more about scaffolding the app. Once the application is ready, navigate to the directory and install all the dependencies: ```bash theme={null} cd vite-project # replace with the name of the project you created npm install ``` After the dependencies are installed, you can start the dev server by running: ```bash theme={null} npm run dev ``` This usually starts the server on port `5173`. Go to [http://localhost:5173](http://localhost:5173) to see your app. The dev server is enabled with [HMR](https://vitejs.dev/guide/features#hot-module-replacement), so it hot reloads the application when you make changes. ## Building Your Production App When it is time to deploy your app for production, simply run: ```bash theme={null} npm run build ``` This command builds a highly optimized static bundle. By default, it uses `/index.html` as the build entry point and produces an application bundle that is suitable to be served over a static hosting service. You can read more about [building for production in the Vite guide](https://vitejs.dev/guide/build.html#building-for-production). The output is found in the `/dist` directory unless configured to a different path. > [!TIP] > > Once built, you can preview the production build using `npm run preview` to start a production-like local web server. > [!WARNING] > > It is important to note that `vite preview` is intended for previewing the build locally and not meant as a production > server. ### Configuring nginx Once the application is built for production, we need a static web server to serve those files. For that purpose, we are using \[Nginx]. Nginx is an open-source HTTP and reverse proxy server. ```nginx nginx.conf.template theme={null} server { listen ${PORT}; server_name _; location / { root /usr/share/nginx/html; try_files $uri $uri/ /index.html; } # skip this block if you don't have a backend yet location /api/ { proxy_pass http://{BACKEND_HOST}:${BACKEND_PORT}; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } error_page 500 502 503 504 /50x.html; location = /50x.html { root /usr/share/nginx/html; } } ``` Create this file `nginx.conf.template` in the root of your project. We won't be using this template now; we'll use it to run the Nginx server inside the Docker container. Note two important blocks in this configuration: ```nginx theme={null} location / { root /usr/share/nginx/html; try_files $uri $uri/ /index.html; } ``` This block serves the `index.html` from the files we built using Ember, stored in the `/usr/share/nginx/html` folder. We will copy the assets to this folder while building the Docker application. And then the API block: ```nginx theme={null} location /api/ { proxy_pass http://{BACKEND_HOST}:${BACKEND_PORT}; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } ``` > [!NOTE] > > You might want to skip the API block if you don't have a backend yet; otherwise, nginx will throw an error for an > invalid host on the backend URL. A typical non-static web application usually will have a backend, and we make AJAX requests using [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) or libraries like [axios](https://axios-http.com/docs/intro) to get/send data to retrieve/store the application state. Assume that the site we built is being served by nginx via the domain `example.com`. Whenever an API call is made to `example.com/api`, the nginx server acts as a reverse proxy server and forwards the request to the backend server. You can use reverse proxying to navigate the traffic that is inbound to nginx. The reverse proxy server also acts as a mask, hiding the real backend from the outside world. ### Create the Docker Image Dockerizing makes the app run anywhere, agnostic of the platform. As long as Docker is installed, whether it's Windows, Mac, or Linux, it can run with the same behavior. Before creating the Dockerfile, let's create a `.dockerignore` file and add the contents that should not be copied over to the Docker file system. ```ignore .dockerignore theme={null} Dockerfile .dockerignore node_modules npm-debug.log README.md .git ``` Read more about [.dockerignore here](https://docs.docker.com/build/building/context/#dockerignore-files). Creating a `.dockerignore` file and adding folders like `node_modules` is a must, since dependencies will be installed while building the image based on the platform preferences used. Copying those from the file system will overwrite the installed dependencies and might cause errors during deployment. Now, create a [Dockerfile](https://docs.docker.com/reference/dockerfile/). The Dockerfile is a text file that contains the instructions for Docker to build the image. The Dockerfile is posted for reference with steps to create the production image. We leverage Docker's [Multi-Stage Builds](https://docs.docker.com/build/building/multi-stage/) to create a smaller-sized image for running the production server. ```docker Dockerfile theme={null} # Stage 1: Base # This stage is the first stage FROM node:20-alpine AS base # Switch to the app directory, # this will be our app's root directory inside the container WORKDIR /app # Copy the manifest and lock file to the root # Note: ./ refers to /app, since we switched context in the above step COPY package.json package-lock.json* ./ # Install the dependencies RUN npm ci # Set the NODE_ENV to production # to configure the application to build/run under production mode ENV NODE_ENV=production # Copy all the files from our machine to the container COPY . . # Run the build to create production assets RUN npm run build # Stage 2: Production # Now we build a new stage from scratch to run the nginx server # This won't include any images from the previous steps FROM nginx:alpine AS production # The port you'd like to use for Nginx ENV PORT=3000 # The URL for the backend service. Skip if irrelevant to you. ENV BACKEND_HOST=host.docker.internal # Port for the backend. Skip if irrelevant to you. ENV BACKEND_PORT=3001 # Copy the template we created earlier for nginx to the etc folder # note the destination file name should be default.conf.template # else the variables in the config won't work COPY nginx.conf.template /etc/nginx/templates/default.conf.template # Since we started a new stage, we need to copy the build from the # build step to the nginx's html directory. Note we have configured # this directory in the nginx config file COPY --from=base /app/dist /usr/share/nginx/html # Expose the port the nginx is running to the outside world EXPOSE ${PORT} # Start the nginx server CMD ["nginx", "-g", "daemon off;"] ``` Now you can build and run the Docker image. To build the Docker image: ```bash theme={null} docker build --platform linux/amd64 -t react-app:latest . ``` This command builds the `react-app` image for the platform `linux/amd64` and tags it as `latest`. If you are locally testing your application, you can skip the `platform` key to build the images. ```bash theme={null} # only for testing in a local machine docker build -t react-app:latest . ``` ### Run the Docker Image Let's run the Docker container using the image created of the React application with the command below. ```bash theme={null} docker run \ -it \ --rm \ --name react-app \ -e PORT=3000 \ -e BACKEND_PORT=3001 \ -e BACKEND_HOST=host.docker.internal \ -d \ -p 3000:3000 \ react-app ``` * `-it`: enables interactivity with TTY. * `--rm`: tells the Docker Daemon to clean up the container and remove the file system after the container exits. * `--name react-app`: Name of the container `react-app`. * `-e PORT=3000`: Sets the environment variable PORT in Docker to `3000`. * `-e BACKEND_PORT=3001`: Sets the environment variable BACKEND\_PORT in Docker to `3001`. * `-e BACKEND_HOST=host.docker.internal`: Sets the environment variable BACKEND\_HOST in Docker to `host.docker.internal`. * `-d`: Runs the container in detached (background) mode. You can skip the flag to see the logs directly in your terminal window. * `-p 3000:3000`: Maps port 3000 on your host to port 3000 in the container. * `react-app` at the end is the name of the image. After running the command, visit `http://localhost:3000` to see the React application running inside the Docker container. Hurray 🎉. Now we have created and packaged a React app for production use. ## Example app ```text theme={null} Source: https://github.com/localopsco/js-example-spa ``` `js-example-spa` is an example TODO app built with. This project is dockerized and the images are published to Amazon Elastic Container Registry (ECR). ## Done 🎉 You can now commit and push the Dockerfile to your git repo. [Create a service](/environment/services/create) now to point at the git repository and branch name to deploy this image. [react]: https://react.dev [npm]: https://docs.npmjs.com/about-npm [vite]: https://vitejs.dev/ [node]: https://nodejs.org/en [docker]: https://docs.docker.com/ [nginx]: https://nginx.org/en/ # VueJS Source: https://docs.localops.co/guides/spa/vue This documentation provides a step-by-step guide to prepare a Single Page Application (SPA) that was built using VueJS for deploying it in any cloud using LocalOps. ## Prerequisites To follow this tutorial, you will need the following: * [Node.js][node], version 20.15.1 at the time of writing. * [npm], as a package manager for installing and maintaining dependencies. This usually comes bundled with Node.js. * A foundational knowledge of [Vue][vuejs]. * [Vite] for a development server and building optimized static assets for production. * [Nginx] to serve static assets and also act as a reverse proxy server. * [Docker] to build standalone containers to serve your production app. > [!NOTE] > > This guide assumes that you have basic knowledge of the above-mentioned technologies and tools. If you are not > familiar with any of them, it is highly recommended to review their official documentation and tutorials to get up to > speed before proceeding with this guide. ## Scaffolding the Vue app Vite offers a CLI tool that makes the scaffolding process much easier. Run the following command: ```bash theme={null} npm create vite@latest ``` Follow the prompts to create your first app. Refer to the [Vite guide](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) to learn more about scaffolding the app. Once the application is ready, navigate to the directory and install all the dependencies: ```bash theme={null} cd vite-project # replace with the name of the project you created npm install ``` After the dependencies are installed, you can start the dev server by running: ```bash theme={null} npm run dev ``` This usually starts the server on port `5173`. Go to [http://localhost:5173](http://localhost:5173) to see your app. The dev server is enabled with [HMR](https://vitejs.dev/guide/features#hot-module-replacement), so it hot reloads the application when you make changes. ## Building Your Production App When it is time to deploy your app for production, simply run: ```bash theme={null} npm run build ``` This command builds a highly optimized static bundle. By default, it uses `/index.html` as the build entry point and produces an application bundle that is suitable to be served over a static hosting service. You can read more about [building for production in the Vite guide](https://vitejs.dev/guide/build.html#building-for-production). The output is found in the `/dist` directory unless configured to a different path. > [!TIP] > > Once built, you can preview the production build using `npm run preview` to start a production-like local web server. > [!NOTE] > > It is important to note that `vite preview` is intended for previewing the build locally and not meant as a production > server. ### Configuring nginx Once the application is built for production, we need a static web server to serve those files. For that purpose, we are using \[Nginx]. Nginx is an open-source HTTP and reverse proxy server. ```nginx nginx.conf.template theme={null} server { listen ${PORT}; server_name _; location / { root /usr/share/nginx/html; try_files $uri $uri/ /index.html; } # skip this block if you don't have a backend yet location /api/ { proxy_pass http://{BACKEND_HOST}:${BACKEND_PORT}; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } error_page 500 502 503 504 /50x.html; location = /50x.html { root /usr/share/nginx/html; } } ``` Create this file `nginx.conf.template` in the root of your project. We won't be using this template now; we'll use it to run the Nginx server inside the Docker container. Note two important blocks in this configuration: ```nginx theme={null} location / { root /usr/share/nginx/html; try_files $uri $uri/ /index.html; } ``` This block serves the `index.html` from the files we built using Ember, stored in the `/usr/share/nginx/html` folder. We will copy the assets to this folder while building the Docker application. And then the API block: ```nginx theme={null} location /api/ { proxy_pass http://{BACKEND_HOST}:${BACKEND_PORT}; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } ``` > [!NOTE] > > You might want to skip the API block if you don't have a backend yet; otherwise, nginx will throw an error for an > invalid host on the backend URL. A typical non-static web application usually will have a backend, and we make AJAX requests using [fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) or libraries like [axios](https://axios-http.com/docs/intro) to get/send data to retrieve/store the application state. Assume that the site we built is being served by nginx via the domain `example.com`. Whenever an API call is made to `example.com/api`, the nginx server acts as a reverse proxy server and forwards the request to the backend server. You can use reverse proxying to navigate the traffic that is inbound to nginx. The reverse proxy server also acts as a mask, hiding the real backend from the outside world. ### Create the Docker Image Dockerizing makes the app run anywhere, agnostic of the platform. As long as Docker is installed, whether it's Windows, Mac, or Linux, it can run with the same behavior. Before creating the Dockerfile, let's create a `.dockerignore` file and add the contents that should not be copied over to the Docker file system. ```ignore .dockerignore theme={null} Dockerfile .dockerignore node_modules npm-debug.log README.md .git ``` Read more about [.dockerignore here](https://docs.docker.com/build/building/context/#dockerignore-files). > [!NOTE] > > Creating a `.dockerignore` file and adding folders like `node_modules` is a must, since dependencies will be installed > while building the image based on the platform preferences used. Copying those from the file system will overwrite the > installed dependencies and might cause errors during deployment. Now, create a [Dockerfile](https://docs.docker.com/reference/dockerfile/). The Dockerfile is a text file that contains the instructions for Docker to build the image. The Dockerfile is posted for reference with steps to create the production image. We leverage Docker's [Multi-Stage Builds](https://docs.docker.com/build/building/multi-stage/) to create a smaller-sized image for running the production server. ```docker title='Dockerfile' theme={null} # Stage 1: Base # This stage is the first stage FROM node:20-alpine AS base # Switch to the app directory, # this will be our app's root directory inside the container WORKDIR /app # Copy the manifest and lock file to the root # Note: ./ refers to /app, since we switched context in the above step COPY package.json package-lock.json* ./ # Install the dependencies RUN npm ci # Set the NODE_ENV to production # to configure the application to build/run under production mode ENV NODE_ENV=production # Copy all the files from our machine to the container COPY . . # Run the build to create production assets RUN npm run build # Stage 2: Production # Now we build a new stage from scratch to run the nginx server # This won't include any images from the previous steps FROM nginx:alpine AS production # The port you'd like to use for Nginx ENV PORT=3000 # The URL for the backend service ENV BACKEND_HOST=host.docker.internal # Port for the backend ENV BACKEND_PORT=3001 # Copy the template we created earlier for nginx to the etc folder # note the destination file name should be default.conf.template # else the variables in the config won't work COPY nginx.conf.template /etc/nginx/templates/default.conf.template # Since we started a new stage, we need to copy the build from the # build step to the nginx's html directory. Note we have configured # this directory in the nginx config file COPY --from=base /app/dist /usr/share/nginx/html # Expose the port the nginx is running to the outside world EXPOSE ${PORT} # Start the nginx server CMD ["nginx", "-g", "daemon off;"] ``` Now you can build and run the Docker image. To build the Docker image: ```bash theme={null} docker build --platform linux/amd64 -t vue-app:latest . ``` This command builds the `vue-app` image for platform `linux/amd64` and tags it as `latest`. If you are locally testing your application, you can skip the `platform` key to build the images ```bash theme={null} # only for testing in local machine docker build -t vue-app:latest . ``` ### Run the docker image Let's run the Docker container using the image created for the Vue application with the command below. ```bash theme={null} docker run \ -it \ --rm \ --name vue-app \ -e PORT=3000 \ -e BACKEND_PORT=3001 \ -e BACKEND_HOST=host.docker.internal \ -d \ -p 3000:3000 \ vue-app ``` * `-it`: Enables interactivity with TTY. * `--rm`: Tells the Docker Daemon to clean up the container and remove the file system after the container exits. * `--name vue-app`: Names the container `vue-app`. * `-e PORT=3000`: Sets the environment variable PORT in Docker to `3000`. * `-e BACKEND_PORT=3001`: Sets the environment variable BACKEND\_PORT in Docker to `3001`. * `-e BACKEND_HOST=host.docker.internal`: Sets the environment variable BACKEND\_HOST in Docker to `host.docker.internal`. * `-d`: Runs the container in detached (background) mode. You can skip this flag to see the logs directly in your terminal window. * `-p 3000:3000`: Maps port 3000 on your host to port 3000 in the container. * `vue-app`: The name of the image. After running the command, visit `http://localhost:3000` to see the Vue application running inside the Docker container. Hurray 🎉. Now we have created and packaged a Vue app for production use. ## Done 🎉 You can now commit and push the Dockerfile to your git repo. [Create a service](/environment/services/create) now to point at the git repository and branch name to deploy this image. [vuejs]: https://vuejs.org/ [npm]: https://docs.npmjs.com/about-npm [vite]: https://vitejs.dev/ [node]: https://nodejs.org/en [docker]: https://docs.docker.com/ [nginx]: https://nginx.org/en/ # How it works Source: https://docs.localops.co/howitworks To deploy your code on a cloud account, LocalOps takes an environment-based approach. After you connect your cloud account, you must create a new environment for each of your deployment environments - test, staging, production, etc., LocalOps will then provision the following set of exclusive cloud resources in the target cloud account to bring the environment up and deploy your services inside. * Virtual private cloud (VPC) * Private subnets * Public subnets * Managed Kubernetes cluster (E.g., EKS in AWS) * Mananged Compute servers and volumes (E.g., EC2 in AWS) * Companion kubernetes deployments to support * Monitoring * Others - Network, Storage, Compute add-ons * 👉 Your code run as "Services" We collectively refer to the above set as “**Environment**”. LocalOps provisions environments using standard in-house provisioning templates and scripts such that you can create any number of environments on any cloud account (AWS, Google Cloud or Azure) and any region. ### Kubernetes cluster All your code is run as docker containers within the kubernetes cluster. Kubernets cluster is created, configured and managed by LocalOps. ### Services You must create a "Service" for each component of your application - backend, frontend, worker etc., to run your code within the kubernetes cluster. You can configure a specific github repo and branch name for each service so that any commit pushed to the branch will automatically get pulled by LocalOps and built & deployed on the Kubernetes cluster. ### Deployments Deployments can be triggered either by pushing your code to the connected github/gitlab repository. Or by manually triggering them from inside LocalOps dashboard. ### Monitoring To debug issues, LocalOps provisions industry standard open source observability suite including Loki, Prometheus and Grafana inside each environment. LocalOps provisions, configures these tools and connects them with each other, so that your team can view Logs and Metrics in a single grafana dashboard, without any configuration. This suite is exclusively provisioned for each environment and runs inside the Kubernetes cluster, right next to your services. ### Cloud Credentials LocalOps needs to have access to your cloud account, to programmatically create all cloud resources required to get the environment running. You can connect your cloud account via keyless, role-based access method from Connections section. ### Exclusive Infrastructure Each environment get its own exclusive set of kubernetes cluster, compute servers and other resources listed above. This is ideal for providing maximum Network, Data & Compute isolation between your deployments & customers. > [!NOTE] > > All cloud infrastructure to run an environment is provisioned in the cloud account chosen while creating the app > environment inside LocalOps. The underlying cloud account will be billed by the cloud provider (say AWS) for the > resources running within each environment. Cloud account's owner has to pay for these charges separately with the > cloud provider. If the cloud account belongs to your customer, they would pay for these cloud resources. ### Security Best Practices: Within each environment, LocalOps turns ON all security best practices suggested by the respective cloud provider. In AWS for example, security groups, disk encryption etc., are all enabled by default. For a detailed overview of all built-in security controls, see the [Security Controls](/environment/security) guide. # First steps Source: https://docs.localops.co/index LocalOps is a cloud native Internal Developer Platform (IDP) that helps developers offer their code as SaaS, BYOC (Bring your own cloud), On-Prem, Self-hosted versions in just a few minutes on *AWS, Google cloud, Azure and any on-prem* environment. No need to write Dockerfiles, Kubernetes helm charts or Terraform/Pulumi scripts. [https://www.loom.com/embed/e2e393d3aa714d3d8d8a084f62e2653e](https://www.loom.com/embed/e2e393d3aa714d3d8d8a084f62e2653e) In less than 30 minutes, provision production grade environments on your cloud account or any cloud account, that comes with * Pre-configured CI/CD pipeline * Fully integrated observability suite * Auto-scaling * Auto-healing * Keyless access to cloud resources and everything else. You can simply connect your Github repo and start pushing code to deploy. > [!TIP] > > [Schedule a 30-min product demo](https://go.localops.co/tour). Our engineers will assist you in getting started. > [!NOTE] > > Before you begin, [create a new account](https://console.localops.co/signup) in LocalOps and complete > onboarding. This will take just 2 mins to complete. This guide provides user manuals, tutorials and concepts to educate your developer teams to start using LocalOps. Here are some first steps: **1. Connect GitHub repository** Connect your github account and repos to start deploying on every git-push. [Connect github now](/accounts/connect-github) **2. Connect your cloud account** Next step is to connect your cloud account (say AWS). [Connect cloud account](/accounts/aws) **3. Launch new environment** Spin up a new environment (say test, staging, production etc.,). [Create new environment](/environment/create) **4. Create a new service** Create a new service within the environment, and configure a branch for auto-deployment. [Create new service](/environment/services/create) **5. Deploy** Once everything is configured, push new commits the configured branch to see automatic deployments triggered. [Learn more](/environment/services/deploy). ### Get support Please write to [support@localops.co](mailto:support@localops.co) in case you have questions. # Migrate from Fly.io Source: https://docs.localops.co/migrate-to-aws/from-fly Step-by-step guide to migrate your Fly.io application and Postgres database to AWS using LocalOps [https://www.loom.com/embed/0bf8ad4510bf401aa429924ad2364a51](https://www.loom.com/embed/0bf8ad4510bf401aa429924ad2364a51) Migrating from Fly.io to AWS gives you access to the full AWS ecosystem, better regional availability, and predictable pricing. LocalOps provides a similar developer experience with git-push deployments and automatic scaling. > [!TIP] > > **White-glove migration**: Our engineers will migrate your Fly.io app to AWS. > [Schedule a migration call](https://go.localops.co/fly) and we'll handle > everything for you. ## What you get after migration * **Same developer experience**: Push to deploy, just like Fly.io * **Predictable costs**: No surprise bills—AWS pricing you control * **Full AWS access**: Use any AWS service (RDS, ElastiCache, S3, SQS, etc.) * **Production-ready**: Auto-scaling, auto-healing, monitoring, and CI/CD out of the box * **Built-in observability**: Open-source stack with Prometheus, Loki, and Grafana—no extra cost * **No vendor lock-in**: Your code runs on standard Kubernetes in your own AWS account ## Migration overview **1. Set up LocalOps environment** Connect your AWS account and create a new environment for your app. **2. Deploy your application** Connect your GitHub repo and deploy your app to LocalOps. **3. Migrate Postgres database** Export your Fly Postgres data and import it into Amazon RDS. **4. Update DNS and go live** Point your domain to the new environment and verify everything works. > [!NOTE] > > Need help? [Schedule a migration call](https://go.localops.co/fly) and our > engineers will assist you through the entire process. ## Step 1: Set up LocalOps environment Before migrating, you need a LocalOps environment running on AWS. **1. Create LocalOps account** [Sign up for LocalOps](https://console.localops.co/signup) if you haven't already. **2. Connect AWS account** Follow the [AWS connection guide](/accounts/aws) to connect your AWS account. **3. Create environment** Create a new environment (e.g., production) in your preferred AWS region. See [Create new environment](/environment/create). **4. Create service** Create a new service and connect your GitHub repository. See [Create new service](/environment/services/create). Once your environment is ready, note down the **VPC ID** and **Private Subnet IDs** from the environment overview page. You'll need these to create your RDS database. ## Step 2: Prepare your application ### Dockerfile-based apps If you have a Dockerfile, LocalOps will use it automatically. No changes needed. ### fly.toml configuration Your `fly.toml` configuration maps to LocalOps concepts: | fly.toml | LocalOps Equivalent | | - | - | | `[http_service]` | [Web service](/environment/services/web) | | `[processes]` | [Workers](/environment/services/workers) | | `[[services]]` | [Internal service](/environment/services/internal) | | `[env]` | Environment variables in service settings | | `[[vm]]` size | Resource configuration in service settings | ### Health checks Convert Fly.io health checks to LocalOps format in `ops.json`: ```json theme={null} { "healthchecks": [ { "type": "http", "path": "/health", "port": 8080, "interval": 30, "timeout": 5 } ] } ``` See [ops.json documentation](/environment/services/ops-json) for all health check options. ### Clustered Elixir/Erlang apps On Fly.io, Elixir apps usually cluster over the private `.internal` network with `dns_cluster` or libcluster. On LocalOps, add `beam_cluster_id` to `ops.json` and point libcluster at the injected `LOPS_BEAM_CLUSTER_DNS`. If your Fly app clustered across regions, you can do the same with one environment per region connected by VPC peering. See [BEAM clustering](/environment/services/beam-clustering) for both setups. ## Step 3: Migrate Fly Postgres to Amazon RDS ### 3.1 Create a backup of your Fly Postgres database Use `flyctl` to connect to your Postgres cluster and create a backup: ```bash theme={null} # Connect to your Fly Postgres app flyctl proxy 5432 -a your-postgres-app-name # In another terminal, create a backup pg_dump "postgres://postgres:your-password@localhost:5432/your-database" \ --format=custom \ --no-owner \ --no-acl \ --file=fly_backup.dump ``` Alternatively, use `flyctl ssh console` to access the database directly: ```bash theme={null} # SSH into the Postgres machine flyctl ssh console -a your-postgres-app-name # Create backup inside the machine pg_dump -U postgres -d your-database -F c -f /tmp/backup.dump # Copy backup to local machine (from another terminal) flyctl sftp get /tmp/backup.dump -a your-postgres-app-name ``` > [!WARNING] > > For large databases, the backup and restore process may take significant time. > Plan for a maintenance window if you need zero data loss during migration. ### 3.2 Create RDS database in your LocalOps environment VPC #### Option A: Using ops.json (Recommended) Add an `ops.json` file to the root of your repository: ```json theme={null} { "dependencies": { "rds": { "instances": [ { "id": "main-db", "prefix": "myapp", "engine": "postgres", "version": "16.4", "storage_gb": 20, "instance_type": "db.t4g.small", "publicly_accessible": false, "exports": { "DATABASE_URL": "$dsn", "DATABASE_HOST": "$address", "DATABASE_NAME": "$dbName", "DATABASE_USER": "$username", "DATABASE_PASSWORD_ARN": "$passwordArn" } } ] } } } ``` Deploy your service to provision the RDS instance automatically. See [RDS documentation](/environment/services/aws/rds) for all configuration options. #### Option B: Manual RDS creation 1. **Login to AWS Console** in the same region as your LocalOps environment 2. **Create a DB Subnet Group**: * Navigate to RDS > Subnet groups > Create DB subnet group * Select the VPC ID from your LocalOps environment * Add the private subnet IDs from your LocalOps environment 3. **Create RDS Instance**: * Navigate to RDS > Create database * Choose PostgreSQL and select the same major version as your Fly database * Select the DB subnet group you created * Set `Publicly accessible` to **No** * Create a security group allowing port 5432 from `10.0.0.0/16` ### 3.3 Restore backup to Amazon RDS ```bash theme={null} # From an EC2 instance in the same VPC sudo dnf install postgresql16 -y # Amazon Linux 2023 # Upload backup scp fly_backup.dump ec2-user@your-ec2-ip:~/ # Restore pg_restore --verbose --no-owner --no-acl \ -h your-rds-endpoint.rds.amazonaws.com \ -U your-db-username \ -d your-database-name \ fly_backup.dump ``` ### 3.4 Configure database credentials If you manually created the RDS instance, add credentials as secrets: 1. Navigate to your service in the LocalOps console 2. Go to Settings > Secrets 3. Add the following secrets: ``` DATABASE_HOST=your-rds-endpoint.rds.amazonaws.com DATABASE_NAME=your-database-name DATABASE_USER=your-db-username DATABASE_PASSWORD=your-db-password ``` > [!TIP] > > If you used `ops.json` to create RDS, there is nothing to add here: the `$dsn` > export gives your service `DATABASE_URL`, with the password already filled in. ## Step 4: Migrate Fly Redis (Upstash) to ElastiCache If you're using Upstash Redis on Fly.io, migrate to Amazon ElastiCache: ```json theme={null} { "dependencies": { "elasticache": { "clusters": [ { "id": "cache", "prefix": "myapp", "engine": "redis", "node_type": "cache.t4g.micro", "exports": { "REDIS_HOST": "$address", "REDIS_PORT": "$port" } } ] } } } ``` Update your connection code: ```javascript theme={null} // Before (Upstash on Fly.io) import { Redis } from "@upstash/redis"; const redis = new Redis({ url: process.env.UPSTASH_REDIS_REST_URL, token: process.env.UPSTASH_REDIS_REST_TOKEN, }); // After (ElastiCache) import Redis from "ioredis"; const redis = new Redis({ host: process.env.REDIS_HOST, port: process.env.REDIS_PORT, }); ``` See [ElastiCache documentation](/environment/services/aws/elasti-cache) for more details. ## Step 5: Migrate environment variables and secrets Export secrets from Fly.io and add them to LocalOps: ```bash theme={null} # List all secrets (names only) flyctl secrets list -a your-app-name ``` For each secret: 1. Get the value from your local environment or source 2. In LocalOps console, navigate to your service > Settings > Secrets 3. Add each variable See [Secrets documentation](/environment/services/secrets) for more details. ## Step 6: Update your application If you created RDS with `ops.json`, your application keeps reading `DATABASE_URL`, just as it did on Fly.io - no code change. The `$dsn` export fills it in with a complete connection URL, password included and already escaped. If you created the database manually, build the URL from the secrets you added in step 3.4 instead: ```javascript theme={null} const connectionString = `postgresql://${process.env.DATABASE_USER}:${encodeURIComponent(process.env.DATABASE_PASSWORD)}@${process.env.DATABASE_HOST}/${process.env.DATABASE_NAME}`; ``` ## Step 7: Deploy and verify 1. Push your changes to trigger a deployment 2. Check logs in the LocalOps console to verify the application starts correctly 3. Test your application endpoints 4. Update your DNS to point to the new LocalOps environment See [Custom domain setup](/environment/services/custom-domain) for DNS configuration. ## Built-in observability Every LocalOps environment comes with a fully integrated open-source observability stack—no extra add-ons required. ### Prometheus + Grafana for metrics [Prometheus](https://prometheus.io/) automatically collects CPU, memory, disk, and network metrics from every node running your application. View and analyze metrics through pre-built [Grafana](https://grafana.com/oss/) dashboards, accessible from the Monitoring tab in your environment. You can filter and group metrics by: * Node * Pod * Deployment * Service * Namespace ### Loki + Grafana for logs [Loki](https://grafana.com/oss/loki/) automatically collects all logs from STDOUT and STDERR across your services. No log drain configuration needed—just print to console and your logs are captured. Access logs through the same Grafana dashboard, with powerful filtering by Kubernetes namespace, deployment, or custom labels. ### Custom dashboards Each environment gets its own Grafana instance with pre-built dashboards for infrastructure monitoring. You can create custom dashboards to visualize application-specific metrics and logs. > [!NOTE] > > Learn more about [logs](/environment/monitoring/logs), > [metrics](/environment/monitoring/metrics), and > [alerts](/environment/monitoring/alerts). ## Migrating Fly.io features | Fly.io Feature | LocalOps Equivalent | | - | - | | Machines (web) | [Web service](/environment/services/web) | | Machines (worker) | [Workers](/environment/services/workers) | | Fly Postgres | [Amazon RDS](/environment/services/aws/rds) | | Upstash Redis | [Amazon ElastiCache](/environment/services/aws/elasti-cache) | | Tigris Object Storage | [Amazon S3](/environment/services/aws/s3) | | Elixir clustering | [BEAM clustering](/environment/services/beam-clustering) | | Fly Metrics | [Built-in metrics](/environment/monitoring/metrics) | | Fly Logs | [Built-in logging](/environment/monitoring/logs) | ## Fly CLI equivalents The [LocalOps CLI](/cli/install-macos) covers the `flyctl` commands you probably ran most often: | Fly CLI | LocalOps CLI | | - | - | | `fly logs` | [`ops logs`](/cli/usage#stream-logs-from-a-service) | | `fly ssh console` | [`ops connect`](/cli/usage#shell-into-a-service) | | `fly proxy` | [`ops proxy`](/cli/usage#forward-a-service-port-to-localhost) | | `fly postgres connect` | [`ops connect --dep`](/cli/usage#open-a-database-shell) | | `fly redis connect` | [`ops connect --dep`](/cli/usage#open-a-database-shell) | ```sh theme={null} ops logs --env production --svc web ops connect --env production --svc web ops connect --env production --svc web --dep main-db ``` Both take the environment and service names you see in your dashboard, so there is no machine id to look up first. When a service runs several pods, `ops logs` reads all of them and prefixes each line with the pod it came from. ## Get help with your migration > [!TIP] > > **White-glove migration**: Don't want to do this yourself? Our engineers will > migrate your entire Fly.io setup to AWS—including database migration, > environment variables, and custom domains. [Schedule a migration call > now](https://go.localops.co/fly). Have questions? Email us at [support@localops.co](mailto:support@localops.co). # Migrate from Heroku Source: https://docs.localops.co/migrate-to-aws/from-heroku Step-by-step guide to migrate your Heroku application and Postgres database to AWS using LocalOps [https://www.loom.com/embed/0bf8ad4510bf401aa429924ad2364a51](https://www.loom.com/embed/0bf8ad4510bf401aa429924ad2364a51) Migrating from Heroku to AWS gives you more control over infrastructure, better cost efficiency at scale, and access to the full AWS ecosystem. LocalOps makes this migration seamless by handling the infrastructure complexity for you. > [!TIP] > > **White-glove migration**: Our engineers will migrate your Heroku app to AWS. [Schedule a migration > call](https://go.localops.co/heroku) and we'll handle everything for you. ## What you get after migration * **Same developer experience**: Push to deploy, just like Heroku * **Lower costs**: AWS infrastructure is typically 40-60% cheaper than Heroku at scale * **Full AWS access**: Use any AWS service (RDS, ElastiCache, S3, SQS, etc.) * **Production-ready**: Auto-scaling, auto-healing, monitoring, and CI/CD out of the box * **Built-in observability**: Open-source stack with Prometheus, Loki, and Grafana—no extra add-ons needed * **No vendor lock-in**: Your code runs on standard Kubernetes in your own AWS account ## Migration overview **1. Set up LocalOps environment** Connect your AWS account and create a new environment for your app. **2. Deploy your application** Connect your GitHub repo and deploy your app to LocalOps. **3. Migrate Postgres database** Export your Heroku Postgres data and import it into Amazon RDS. **4. Update DNS and go live** Point your domain to the new environment and verify everything works. > [!NOTE] > > Need help? [Schedule a migration call](https://go.localops.co/heroku) and our engineers will assist you through the > entire process. ## Step 1: Set up LocalOps environment Before migrating, you need a LocalOps environment running on AWS. **1. Create LocalOps account** [Sign up for LocalOps](https://console.localops.co/signup) if you haven't already. **2. Connect AWS account** Follow the [AWS connection guide](/accounts/aws) to connect your AWS account. **3. Create environment** Create a new environment (e.g., production) in your preferred AWS region. See [Create new environment](/environment/create). **4. Create service** Create a new service and connect your GitHub repository. See [Create new service](/environment/services/create). Once your environment is ready, note down the **VPC ID** and **Private Subnet IDs** from the environment overview page. You'll need these to create your RDS database. ## Step 2: Migrate Heroku Postgres to Amazon RDS ### 2.1 Create a backup of your Heroku Postgres database First, create a manual backup of your Heroku Postgres database: ```bash theme={null} # Install Heroku CLI if not already installed brew install heroku/brew/heroku # Login to Heroku heroku login # Create a manual backup heroku pg:backups:capture --app your-heroku-app-name # Download the backup heroku pg:backups:download --app your-heroku-app-name ``` This downloads a file called `latest.dump` to your current directory. > [!WARNING] > > For large databases, the backup and restore process may take significant time. Plan for a maintenance window if you > need zero data loss during migration. ### 2.2 Create RDS database in your LocalOps environment VPC You can either use the declarative `ops.json` approach (recommended) or create the database manually. #### Option A: Using ops.json (Recommended) Add an `ops.json` file to the root of your repository: ```json theme={null} { "dependencies": { "rds": { "instances": [ { "id": "main-db", "prefix": "myapp", "engine": "postgres", "version": "16.4", "storage_gb": 20, "instance_type": "db.t4g.small", "publicly_accessible": false, "exports": { "DATABASE_HOST": "$address", "DATABASE_NAME": "$dbName", "DATABASE_USER": "$username", "DATABASE_PASSWORD_ARN": "$passwordArn" } } ] } } } ``` Deploy your service to provision the RDS instance automatically. See [RDS documentation](/environment/services/aws/rds) for all configuration options. #### Option B: Manual RDS creation If you prefer to create the database manually: 1. **Login to AWS Console** in the same region as your LocalOps environment 2. **Create a DB Subnet Group**: * Navigate to RDS > Subnet groups > Create DB subnet group * Select the VPC ID from your LocalOps environment * Add the private subnet IDs from your LocalOps environment * Save the subnet group 3. **Create RDS Instance**: * Navigate to RDS > Create database * Choose PostgreSQL and select the same major version as your Heroku database * Select the DB subnet group you created * Configure instance size (start with `db.t4g.small` for small apps) * Set `Publicly accessible` to **No** * Create or select a security group that allows inbound traffic on port 5432 from `10.0.0.0/16` (your VPC CIDR) 4. **Record connection details**: Note down the endpoint, username, and password ### 2.3 Restore backup to Amazon RDS To restore your Heroku backup to RDS, you need a machine that can access both the backup file and the RDS instance. #### Option 1: Use an EC2 instance in the same VPC ```bash theme={null} # Launch a small EC2 instance in your LocalOps VPC # SSH into the instance and install PostgreSQL client sudo dnf install postgresql16 -y # Amazon Linux 2023 # Upload your backup file to the EC2 instance scp latest.dump ec2-user@your-ec2-ip:~/ # Restore the backup to RDS pg_restore --verbose --no-owner --no-acl \ -h your-rds-endpoint.rds.amazonaws.com \ -U your-db-username \ -d your-database-name \ latest.dump ``` #### Option 2: Use AWS Database Migration Service (DMS) For larger databases or if you need continuous replication during migration, use [AWS DMS](https://docs.aws.amazon.com/dms/latest/userguide/Welcome.html). ### 2.4 Configure database credentials in LocalOps If you manually created the RDS instance, add the database credentials as secrets in your LocalOps service: 1. Navigate to your service in the LocalOps console 2. Go to Settings > Secrets 3. Add the following secrets: ``` DATABASE_HOST=your-rds-endpoint.rds.amazonaws.com DATABASE_NAME=your-database-name DATABASE_USER=your-db-username DATABASE_PASSWORD=your-db-password ``` See [Secrets documentation](/environment/services/secrets) for more details. ## Step 3: Update your application Update your application code to use the new environment variables: ```javascript theme={null} // Before (Heroku) const connectionString = process.env.DATABASE_URL; // After (LocalOps) const connectionString = `postgresql://${process.env.DATABASE_USER}:${password}@${process.env.DATABASE_HOST}/${process.env.DATABASE_NAME}`; ``` > [!TIP] > > If you used `ops.json` to create RDS, the password is stored in AWS Secrets Manager. Use the AWS SDK to retrieve it > using the `DATABASE_PASSWORD_ARN` environment variable. ## Step 4: Deploy and verify 1. Push your changes to trigger a deployment 2. Check logs in the LocalOps console to verify the application starts correctly 3. Test your application endpoints 4. Update your DNS to point to the new LocalOps environment If you would rather watch the rollout from your terminal, the way you did with `heroku logs --tail`, install the [LocalOps CLI](/cli/install-macos) and stream the service directly: ```sh theme={null} ops logs --env production --svc web ``` See [Custom domain setup](/environment/services/custom-domain) for DNS configuration. ## Built-in observability Every LocalOps environment comes with a fully integrated open-source observability stack—no paid add-ons like Papertrail or New Relic required. ### Prometheus + Grafana for metrics [Prometheus](https://prometheus.io/) automatically collects CPU, memory, disk, and network metrics from every node running your application. View and analyze metrics through pre-built [Grafana](https://grafana.com/oss/) dashboards, accessible from the Monitoring tab in your environment. You can filter and group metrics by: * Node * Pod * Deployment * Service * Namespace ### Loki + Grafana for logs [Loki](https://grafana.com/oss/loki/) automatically collects all logs from STDOUT and STDERR across your services. No log drain configuration needed—just print to console and your logs are captured. Access logs through the same Grafana dashboard, with powerful filtering by Kubernetes namespace, deployment, or custom labels. ### Custom dashboards Each environment gets its own Grafana instance with pre-built dashboards for infrastructure monitoring. You can create custom dashboards to visualize application-specific metrics and logs. > [!NOTE] > > Learn more about [logs](/environment/monitoring/logs), [metrics](/environment/monitoring/metrics), and > [alerts](/environment/monitoring/alerts). ## Migrating other Heroku add-ons | Heroku Add-on | AWS Equivalent | | - | - | | Heroku Redis | [Amazon ElastiCache](/environment/services/aws/elasti-cache) | | Heroku Postgres | [Amazon RDS](/environment/services/aws/rds) | | CloudAMQP | [Amazon SQS](/environment/services/aws/sqs) | | Papertrail / Logentries | [Built-in logging](/environment/monitoring/logs) | | New Relic / Scout | [Built-in metrics](/environment/monitoring/metrics) | | Scheduler | [Cron jobs](/environment/services/cronjob) | ## Heroku CLI equivalents The [LocalOps CLI](/cli/install-macos) covers the commands you probably ran most often: | Heroku CLI | LocalOps CLI | | - | - | | `heroku logs --tail` | [`ops logs`](/cli/usage#stream-logs-from-a-service) | | `heroku run bash` | [`ops connect`](/cli/usage#shell-into-a-service) | | `heroku config` | `ops connect --env --svc -- printenv` | | `heroku pg:psql` | [`ops connect --dep`](/cli/usage#open-a-database-shell) | | `heroku redis:cli` | [`ops connect --dep`](/cli/usage#open-a-database-shell) | ```sh theme={null} ops logs --env production --svc web ops connect --env production --svc web ``` Unlike `heroku run`, `ops connect` opens a shell on a pod that is already serving traffic rather than starting a fresh one-off dyno. Anything you change there is lost when the pod is replaced, so use it to inspect and debug. Run one-off tasks as a [job service](/environment/services/job) instead. ## Get help with your migration > [!TIP] > > **White-glove migration**: Don't want to do this yourself? Our engineers will migrate your entire Heroku setup to > AWS—including database migration, environment variables, and custom domains. [Schedule a migration call > now](https://go.localops.co/heroku). Have questions? Email us at [support@localops.co](mailto:support@localops.co). # Migrate from Render Source: https://docs.localops.co/migrate-to-aws/from-render Step-by-step guide to migrate your Render application and Postgres database to AWS using LocalOps [https://www.loom.com/embed/0bf8ad4510bf401aa429924ad2364a51](https://www.loom.com/embed/0bf8ad4510bf401aa429924ad2364a51) Migrating from Render to AWS gives you more control over infrastructure, predictable pricing at scale, and access to the full AWS ecosystem. LocalOps makes this migration seamless by providing the same developer experience you're used to on Render. > [!TIP] > > **White-glove migration**: Our engineers will migrate your Render app to AWS. > [Schedule a migration call](https://go.localops.co/render) and we'll handle > everything for you. ## What you get after migration * **Same developer experience**: Push to deploy, just like Render * **Predictable costs**: No surprise bills from auto-scaling—AWS pricing you control * **Full AWS access**: Use any AWS service (RDS, ElastiCache, S3, SQS, etc.) * **Production-ready**: Auto-scaling, auto-healing, monitoring, and CI/CD out of the box * **Built-in observability**: Open-source stack with Prometheus, Loki, and Grafana—no extra cost * **No vendor lock-in**: Your code runs on standard Kubernetes in your own AWS account ## Migration overview **1. Set up LocalOps environment** Connect your AWS account and create a new environment for your app. **2. Deploy your application** Connect your GitHub repo and deploy your app to LocalOps. **3. Migrate Postgres database** Export your Render Postgres data and import it into Amazon RDS. **4. Update DNS and go live** Point your domain to the new environment and verify everything works. > [!NOTE] > > Need help? [Schedule a migration call](https://go.localops.co/render) and our > engineers will assist you through the entire process. ## Step 1: Set up LocalOps environment Before migrating, you need a LocalOps environment running on AWS. **1. Create LocalOps account** [Sign up for LocalOps](https://console.localops.co/signup) if you haven't already. **2. Connect AWS account** Follow the [AWS connection guide](/accounts/aws) to connect your AWS account. **3. Create environment** Create a new environment (e.g., production) in your preferred AWS region. See [Create new environment](/environment/create). **4. Create service** Create a new service and connect your GitHub repository. See [Create new service](/environment/services/create). Once your environment is ready, note down the **VPC ID** and **Private Subnet IDs** from the environment overview page. You'll need these to create your RDS database. ## Step 2: Migrate Render Postgres to Amazon RDS ### 2.1 Create a backup of your Render Postgres database Render provides external connection strings for Postgres databases. Use `pg_dump` to create a backup: ```bash theme={null} # Get your external connection string from Render dashboard # Dashboard > Your Database > Connections > External Connection String # Create a backup using pg_dump pg_dump "your-render-external-connection-string" \ --format=custom \ --no-owner \ --no-acl \ --file=render_backup.dump ``` Alternatively, you can create a backup from the Render dashboard: 1. Navigate to your Postgres database in the Render dashboard 2. Go to the **Backups** tab 3. Click **Create Backup** to create a manual backup 4. Download the backup file > [!WARNING] > > For large databases, the backup and restore process may take significant time. > Plan for a maintenance window if you need zero data loss during migration. ### 2.2 Create RDS database in your LocalOps environment VPC You can either use the declarative `ops.json` approach (recommended) or create the database manually. #### Option A: Using ops.json (Recommended) Add an `ops.json` file to the root of your repository: ```json theme={null} { "dependencies": { "rds": { "instances": [ { "id": "main-db", "prefix": "myapp", "engine": "postgres", "version": "16.4", "storage_gb": 20, "instance_type": "db.t4g.small", "publicly_accessible": false, "exports": { "DATABASE_URL": "$dsn", "DATABASE_HOST": "$address", "DATABASE_NAME": "$dbName", "DATABASE_USER": "$username", "DATABASE_PASSWORD_ARN": "$passwordArn" } } ] } } } ``` Deploy your service to provision the RDS instance automatically. See [RDS documentation](/environment/services/aws/rds) for all configuration options. #### Option B: Manual RDS creation If you prefer to create the database manually: 1. **Login to AWS Console** in the same region as your LocalOps environment 2. **Create a DB Subnet Group**: * Navigate to RDS > Subnet groups > Create DB subnet group * Select the VPC ID from your LocalOps environment * Add the private subnet IDs from your LocalOps environment * Save the subnet group 3. **Create RDS Instance**: * Navigate to RDS > Create database * Choose PostgreSQL and select the same major version as your Render database * Select the DB subnet group you created * Configure instance size (start with `db.t4g.small` for small apps) * Set `Publicly accessible` to **No** * Create or select a security group that allows inbound traffic on port 5432 from `10.0.0.0/16` (your VPC CIDR) 4. **Record connection details**: Note down the endpoint, username, and password ### 2.3 Restore backup to Amazon RDS To restore your Render backup to RDS, you need a machine that can access both the backup file and the RDS instance. #### Option 1: Use an EC2 instance in the same VPC ```bash theme={null} # Launch a small EC2 instance in your LocalOps VPC # SSH into the instance and install PostgreSQL client sudo dnf install postgresql16 -y # Amazon Linux 2023 # Upload your backup file to the EC2 instance scp render_backup.dump ec2-user@your-ec2-ip:~/ # Restore the backup to RDS pg_restore --verbose --no-owner --no-acl \ -h your-rds-endpoint.rds.amazonaws.com \ -U your-db-username \ -d your-database-name \ render_backup.dump ``` #### Option 2: Use AWS Database Migration Service (DMS) For larger databases or if you need continuous replication during migration, use [AWS DMS](https://docs.aws.amazon.com/dms/latest/userguide/Welcome.html). ### 2.4 Configure database credentials in LocalOps If you manually created the RDS instance, add the database credentials as secrets in your LocalOps service: 1. Navigate to your service in the LocalOps console 2. Go to Settings > Secrets 3. Add the following secrets: ``` DATABASE_HOST=your-rds-endpoint.rds.amazonaws.com DATABASE_NAME=your-database-name DATABASE_USER=your-db-username DATABASE_PASSWORD=your-db-password ``` See [Secrets documentation](/environment/services/secrets) for more details. ## Step 3: Migrate environment variables Export your environment variables from Render and add them to LocalOps: 1. In Render dashboard, go to your service > Environment 2. Copy each environment variable 3. In LocalOps console, navigate to your service > Settings > Secrets 4. Add each variable as a secret > [!TIP] > > For environment-specific variables, LocalOps lets you configure different > values per environment (test, staging, production) from a single service > configuration. ## Step 4: Update your application If you created RDS with `ops.json`, your application keeps reading `DATABASE_URL` - Render's default - with no code change. The `$dsn` export fills it in with a complete connection URL: host, database, username and password, already escaped. If you created the database manually (Option B), build the URL from the secrets you added in step 2.4 instead: ```javascript theme={null} const connectionString = `postgresql://${process.env.DATABASE_USER}:${encodeURIComponent(process.env.DATABASE_PASSWORD)}@${process.env.DATABASE_HOST}/${process.env.DATABASE_NAME}`; ``` > [!WARNING] > > `DATABASE_URL` embeds the database password. Treat the value as a secret - don't log it or paste it anywhere. ## Step 5: Deploy and verify 1. Push your changes to trigger a deployment 2. Check logs in the LocalOps console to verify the application starts correctly 3. Test your application endpoints 4. Update your DNS to point to the new LocalOps environment Once it is up, the [LocalOps CLI](/cli/install-macos) gives you two useful checks from your terminal, streaming the service's logs, and opening a SQL shell on the migrated database to confirm the data landed: ```sh theme={null} ops logs --env production --svc web ops connect --env production --svc web --dep main-db ``` See [Custom domain setup](/environment/services/custom-domain) for DNS configuration. ## Built-in observability Every LocalOps environment comes with a fully integrated open-source observability stack—no paid add-ons required. ### Prometheus + Grafana for metrics [Prometheus](https://prometheus.io/) automatically collects CPU, memory, disk, and network metrics from every node running your application. View and analyze metrics through pre-built [Grafana](https://grafana.com/oss/) dashboards, accessible from the Monitoring tab in your environment. You can filter and group metrics by: * Node * Pod * Deployment * Service * Namespace ### Loki + Grafana for logs [Loki](https://grafana.com/oss/loki/) automatically collects all logs from STDOUT and STDERR across your services. No log drain configuration needed—just print to console and your logs are captured. Access logs through the same Grafana dashboard, with powerful filtering by Kubernetes namespace, deployment, or custom labels. ### Custom dashboards Each environment gets its own Grafana instance with pre-built dashboards for infrastructure monitoring. You can create custom dashboards to visualize application-specific metrics and logs. > [!NOTE] > > Learn more about [logs](/environment/monitoring/logs), > [metrics](/environment/monitoring/metrics), and > [alerts](/environment/monitoring/alerts). ## Migrating other Render services | Render Service | LocalOps Equivalent | | - | - | | Web Service | [Web service](/environment/services/web) | | Background Worker | [Workers](/environment/services/workers) | | Cron Job | [Cron jobs](/environment/services/cronjob) | | Private Service | [Internal service](/environment/services/internal) | | Render Postgres | [Amazon RDS](/environment/services/aws/rds) | | Render Redis | [Amazon ElastiCache](/environment/services/aws/elasti-cache) | ## Get help with your migration > [!TIP] > > **White-glove migration**: Don't want to do this yourself? Our engineers will > migrate your entire Render setup to AWS—including database migration, > environment variables, and custom domains. [Schedule a migration call > now](https://go.localops.co/render). Have questions? Email us at [support@localops.co](mailto:support@localops.co). # Migrate from Vercel Source: https://docs.localops.co/migrate-to-aws/from-vercel Step-by-step guide to migrate your Vercel application and database to AWS using LocalOps [https://www.loom.com/embed/0bf8ad4510bf401aa429924ad2364a51](https://www.loom.com/embed/0bf8ad4510bf401aa429924ad2364a51) Migrating from Vercel to AWS gives you more control over infrastructure, predictable pricing without per-request costs, and access to the full AWS ecosystem. LocalOps provides the same git-push deployment experience you're used to on Vercel. > [!TIP] > > **White-glove migration**: Our engineers will migrate your Vercel app to AWS. [Schedule a migration > call](https://go.localops.co/vercel) and we'll handle everything for you. ## What you get after migration * **Same developer experience**: Push to deploy, just like Vercel * **Predictable costs**: No per-request pricing or surprise bills from traffic spikes * **Full AWS access**: Use any AWS service (RDS, ElastiCache, S3, SQS, etc.) * **Production-ready**: Auto-scaling, auto-healing, monitoring, and CI/CD out of the box * **Built-in observability**: Open-source stack with Prometheus, Loki, and Grafana—no extra cost * **No vendor lock-in**: Your code runs on standard Kubernetes in your own AWS account ## Migration overview **1. Set up LocalOps environment** Connect your AWS account and create a new environment for your app. **2. Deploy your application** Connect your GitHub repo and deploy your app to LocalOps. **3. Migrate database** Export your Vercel Postgres data and import it into Amazon RDS. **4. Update DNS and go live** Point your domain to the new environment and verify everything works. > [!NOTE] > > Need help? [Schedule a migration call](https://go.localops.co/vercel) and our engineers will assist you through the > entire process. ## Step 1: Set up LocalOps environment Before migrating, you need a LocalOps environment running on AWS. **1. Create LocalOps account** [Sign up for LocalOps](https://console.localops.co/signup) if you haven't already. **2. Connect AWS account** Follow the [AWS connection guide](/accounts/aws) to connect your AWS account. **3. Create environment** Create a new environment (e.g., production) in your preferred AWS region. See [Create new environment](/environment/create). **4. Create service** Create a new service and connect your GitHub repository. See [Create new service](/environment/services/create). Once your environment is ready, note down the **VPC ID** and **Private Subnet IDs** from the environment overview page. You'll need these to create your RDS database. ## Step 2: Prepare your application ### Next.js applications If you're running a Next.js app, LocalOps automatically detects and builds it. Your app will run as a Node.js server rather than serverless functions, which provides: * Faster cold starts * Persistent connections to databases * WebSocket support * No function timeout limits No code changes are typically required. LocalOps handles the build and deployment automatically. ### Serverless functions If you're using Vercel Serverless Functions, convert them to standard API routes: ```javascript theme={null} // Before (Vercel serverless function) // api/hello.js export default function handler(req, res) { res.status(200).json({ message: 'Hello' }); } // After (Next.js API route - works the same) // pages/api/hello.js or app/api/hello/route.js export default function handler(req, res) { res.status(200).json({ message: 'Hello' }); } ``` Next.js API routes work identically on LocalOps without modification. ### Edge functions Edge Functions need to be converted to standard API routes or middleware. Since your app runs on AWS infrastructure close to your users, latency differences are minimal. ## Step 3: Migrate Vercel Postgres to Amazon RDS If you're using Vercel Postgres, follow these steps to migrate to Amazon RDS. ### 3.1 Create a backup of your Vercel Postgres database Get your connection string from the Vercel dashboard and use `pg_dump`: ```bash theme={null} # Get connection string from Vercel dashboard # Project Settings > Storage > Your Database > .env.local tab # Create a backup using pg_dump pg_dump "$POSTGRES_URL" \ --format=custom \ --no-owner \ --no-acl \ --file=vercel_backup.dump ``` > [!WARNING] > > For large databases, the backup and restore process may take significant time. Plan for a maintenance window if you > need zero data loss during migration. ### 3.2 Create RDS database in your LocalOps environment VPC #### Option A: Using ops.json (Recommended) Add an `ops.json` file to the root of your repository: ```json theme={null} { "dependencies": { "rds": { "instances": [ { "id": "main-db", "prefix": "myapp", "engine": "postgres", "version": "16.4", "storage_gb": 20, "instance_type": "db.t4g.small", "publicly_accessible": false, "exports": { "DATABASE_URL": "$dsn", "DATABASE_HOST": "$address", "DATABASE_NAME": "$dbName", "DATABASE_USER": "$username", "DATABASE_PASSWORD_ARN": "$passwordArn" } } ] } } } ``` Deploy your service to provision the RDS instance automatically. See [RDS documentation](/environment/services/aws/rds) for all configuration options. #### Option B: Manual RDS creation 1. **Login to AWS Console** in the same region as your LocalOps environment 2. **Create a DB Subnet Group**: * Navigate to RDS > Subnet groups > Create DB subnet group * Select the VPC ID from your LocalOps environment * Add the private subnet IDs from your LocalOps environment 3. **Create RDS Instance**: * Navigate to RDS > Create database * Choose PostgreSQL * Select the DB subnet group you created * Set `Publicly accessible` to **No** * Create a security group allowing port 5432 from `10.0.0.0/16` ### 3.3 Restore backup to Amazon RDS ```bash theme={null} # From an EC2 instance in the same VPC pg_restore --verbose --no-owner --no-acl \ -h your-rds-endpoint.rds.amazonaws.com \ -U your-db-username \ -d your-database-name \ vercel_backup.dump ``` ### 3.4 Update database connection Update your application to use the new database: ```javascript theme={null} // Before (Vercel Postgres) import { sql } from '@vercel/postgres'; const result = await sql`SELECT * FROM users`; // After (standard pg client) import { Pool } from 'pg'; const pool = new Pool({ connectionString: process.env.DATABASE_URL }); const result = await pool.query('SELECT * FROM users'); ``` > [!TIP] > > `DATABASE_URL` comes from the `$dsn` export in `ops.json`: a complete connection URL with the host, database, username > and password already filled in and escaped. It embeds the password, so treat the value as a secret. > > If you created the database manually (Option B), add `DATABASE_URL` as a [secret](/environment/services/secrets) on your > service yourself, in the form `postgresql://:@:5432/` - percent-encode any > special characters in the password. ## Step 4: Migrate Vercel KV (Redis) to ElastiCache If you're using Vercel KV, migrate to Amazon ElastiCache: ```json theme={null} { "dependencies": { "elasticache": { "clusters": [ { "id": "cache", "prefix": "myapp", "engine": "redis", "node_type": "cache.t4g.micro", "exports": { "REDIS_HOST": "$address", "REDIS_PORT": "$port" } } ] } } } ``` Update your code to use a standard Redis client: ```javascript theme={null} // Before (Vercel KV) import { kv } from '@vercel/kv'; await kv.set('key', 'value'); // After (ioredis) import Redis from 'ioredis'; const redis = new Redis({ host: process.env.REDIS_HOST, port: process.env.REDIS_PORT, }); await redis.set('key', 'value'); ``` See [ElastiCache documentation](/environment/services/aws/elasti-cache) for more details. ## Step 5: Migrate Vercel Blob to S3 If you're using Vercel Blob, migrate to Amazon S3: ```json theme={null} { "dependencies": { "s3": { "buckets": [ { "id": "uploads", "prefix": "myapp", "exports": { "S3_BUCKET": "$name", "S3_REGION": "$region" } } ] } } } ``` Update your code to use the AWS SDK: ```javascript theme={null} // Before (Vercel Blob) import { put } from '@vercel/blob'; const blob = await put('file.txt', 'Hello World', { access: 'public' }); // After (AWS SDK) import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'; const s3 = new S3Client({ region: process.env.S3_REGION }); await s3.send( new PutObjectCommand({ Bucket: process.env.S3_BUCKET, Key: 'file.txt', Body: 'Hello World', }), ); ``` See [S3 documentation](/environment/services/aws/s3) for more details. ## Step 6: Migrate environment variables 1. In Vercel dashboard, go to Project Settings > Environment Variables 2. Export or copy each variable 3. In LocalOps console, navigate to your service > Settings > Secrets 4. Add each variable as a secret See [Secrets documentation](/environment/services/secrets) for more details. ## Step 7: Deploy and verify 1. Push your changes to trigger a deployment 2. Check logs in the LocalOps console to verify the application starts correctly 3. Test your application endpoints 4. Update your DNS to point to the new LocalOps environment Once it is up, the [LocalOps CLI](/cli/install-macos) gives you a few useful checks from your terminal - streaming the service's logs, opening a SQL shell on the migrated database to confirm the data landed, and a `redis-cli` on the cache: ```sh theme={null} ops logs --env production --svc web ops connect --env production --svc web --dep main-db ops connect --env production --svc web --dep cache ``` See [Custom domain setup](/environment/services/custom-domain) for DNS configuration. ## Built-in observability Every LocalOps environment comes with a fully integrated open-source observability stack—no paid add-ons required. ### Prometheus + Grafana for metrics [Prometheus](https://prometheus.io/) automatically collects CPU, memory, disk, and network metrics from every node running your application. View and analyze metrics through pre-built [Grafana](https://grafana.com/oss/) dashboards, accessible from the Monitoring tab in your environment. You can filter and group metrics by: * Node * Pod * Deployment * Service * Namespace ### Loki + Grafana for logs [Loki](https://grafana.com/oss/loki/) automatically collects all logs from STDOUT and STDERR across your services. No log drain configuration needed—just print to console and your logs are captured. Access logs through the same Grafana dashboard, with powerful filtering by Kubernetes namespace, deployment, or custom labels. ### Custom dashboards Each environment gets its own Grafana instance with pre-built dashboards for infrastructure monitoring. You can create custom dashboards to visualize application-specific metrics and logs. > [!NOTE] > > Learn more about [logs](/environment/monitoring/logs), [metrics](/environment/monitoring/metrics), and > [alerts](/environment/monitoring/alerts). ## Migrating Vercel features | Vercel Feature | LocalOps Equivalent | | - | - | | Web Deployments | [Web service](/environment/services/web) | | Serverless Functions | API routes in your app | | Cron Jobs | [Cron jobs](/environment/services/cronjob) | | Vercel Postgres | [Amazon RDS](/environment/services/aws/rds) | | Vercel KV | [Amazon ElastiCache](/environment/services/aws/elasti-cache) | | Vercel Blob | [Amazon S3](/environment/services/aws/s3) | | Vercel Analytics | [Built-in metrics](/environment/monitoring/metrics) | | Log Drains | [Built-in logging](/environment/monitoring/logs) | ## Get help with your migration > [!TIP] > > **White-glove migration**: Don't want to do this yourself? Our engineers will migrate your entire Vercel setup to > AWS—including database migration, environment variables, and custom domains. [Schedule a migration call > now](https://go.localops.co/vercel). Have questions? Email us at [support@localops.co](mailto:support@localops.co). # Privacy Policy Source: https://docs.localops.co/privacy-policy How LocalOps collects, uses, maintains, protects, and discloses information from users of the LocalOps platform. > [!NOTE] > > **Last updated:** June 6, 2026 ## Introduction LocalOps Inc., a Delaware corporation ("Company," "we," or "us") respects your privacy and is committed to protecting it through our compliance with this policy. This policy describes the types of information we may collect from you during your access to and use of [LocalOps.co](https://localops.co), [console.localops.co](https://console.localops.co), [lookout.localops.co](https://lookout.localops.co), and any other related sub-domains (collectively, the "Website"), including any content, functionality, and services of the Company, including private spaces, environments, and other services (collectively, the "Services" and together with the Website, the "Platform") and our practices for collecting, using, maintaining, protecting, and disclosing that information. The Platform allows users ("Users") to create private spaces and install applications from our app universe into their private space and use them. This policy applies to information we collect: * On the Platform. * In email, text, SMS, and other electronic messages between you and the Platform. * Through mobile and/or desktop applications or material you download from the Platform, which may provide dedicated non-browser-based interaction between you and the Platform. It does not apply to information collected by: * Us offline or through any other means, including on any other website operated by Company or any third party (including our affiliates and subsidiaries); or * Any third party (including our affiliates and subsidiaries), including through any application or content (including advertising) that may link to or be accessible from or on the Platform. Please read this policy carefully to understand our policies and practices regarding your information and how we will treat it. If you do not agree with our policies and practices, your choice is not to use our Platform. By accessing or using the Platform, you agree to this privacy policy. This policy may change from time to time, so please see the "Changes to Our Privacy Policy" section below. Your continued use of the Platform after we make changes is deemed to be acceptance of those changes, so please check the policy periodically for updates. ## Information We Collect About You and How We Collect It We collect several types of information from and about users of our Platform, including information: * By which you may be personally identified, such as name, postal address, e-mail address, telephone number, social media account information, images and videos, location, or any other identifier by which you may be contacted online or offline ("personal information"); * That is about you but individually does not identify you; and/or * About your internet connection, the equipment you use to access our Platform, and usage details. We collect this information: * Directly from you when you provide it to us. * Automatically as you navigate through the site. Information collected automatically may include usage details, IP addresses, and information collected through cookies, web beacons, and other tracking technologies. * From third parties, for example, our business partners. ### Information You Provide to Us The information we collect on or through our Platform may include: * Information that you provide by filling in forms on our Platform. This includes information provided at the time of registering to use our Platform, or requesting further services. We may also ask you for information when you report a problem with our Platform. * Records and copies of your correspondence (including email addresses), if you contact us. * Details of transactions you carry out through our Platform and of the fulfillment of your orders for services. You may be required to provide financial information before placing an order through our Platform. * Information you provide to third parties via the Platform. * Your search queries on the Platform. * Billing or payment information. > [!NOTE] > > Personal information obtained from you will never be shared, sold, or transferred outside of the Platform without your > consent. You also may provide information to be published or displayed (hereinafter, "posted") on public areas of the Platform, if any, or transmitted to other users of the Platform or third parties (collectively, "User Contributions"). Your User Contributions are posted on and transmitted to others at your own risk. Although you may set certain privacy settings for such information by logging into your account profile, please be aware that no security measures are perfect or impenetrable. Additionally, we cannot control the actions of other users of the Platform with whom you may choose to share your User Contributions. Therefore, we cannot and do not guarantee that your User Contributions will not be viewed by unauthorized persons. ### Information We Collect Through Automatic Data Collection Technologies As you navigate through and interact with our Platform, we may use automatic data collection technologies to collect certain information about your equipment, browsing actions, and patterns, including: * Details of your visits to our Platform, including traffic data, location data, logs, and other communication data and the resources that you access and use on the Platform. * Information about your computer and internet connection, including your IP address, operating system, and browser type. We also may use these technologies to collect information about your online activities over time and across third-party websites or other online services (behavioral tracking). The information we collect automatically may include personal information, and we may maintain it or associate it with personal information we collect in other ways or receive from third parties. It helps us to improve our Platform and to deliver a better and more personalized service, including by enabling us to: * Estimate our audience size and usage patterns. * Store information about your preferences, allowing us to customize our Platform according to your individual interests. * Speed up your searches. * Recognize you when you return to our Platform. The technologies we use for this automatic data collection may include: * **Cookies (or browser cookies).** A cookie is a small file placed on the hard drive of your computer. You may refuse to accept browser cookies by activating the appropriate setting on your browser. However, if you select this setting you may be unable to access certain parts of our Platform. Unless you have adjusted your browser setting so that it will refuse cookies, our system will issue cookies when you direct your browser to our Platform. * **Flash Cookies.** Certain features of our Platform may use local stored objects (or Flash cookies) to collect and store information about your preferences and navigation to, from, and on our Platform. Flash cookies are not managed by the same browser settings as are used for browser cookies. For information about managing your privacy and security settings for Flash cookies, see "Choices About How We Use and Disclose Your Information" below. * **Web Beacons.** Pages of the Platform and our e-mails may contain small electronic files known as web beacons (also referred to as clear gifs, pixel tags, and single-pixel gifs) that permit the Company, for example, to count users who have visited those pages or opened an email and for other related website statistics (for example, recording the popularity of certain website content and verifying system and server integrity). ## Third-Party Use of Cookies and Other Tracking Technologies Some content or applications on the Platform are served by third-parties, including advertisers, ad networks and servers, content providers, communication providers, and application providers. These third parties may use cookies alone or in conjunction with web beacons or other tracking technologies to collect information about you when you use our website. The information they collect may be associated with your personal information or they may collect information, including personal information, about your online activities over time and across different websites and other online services. They may use this information to provide you with interest-based (behavioral) advertising or other targeted content. We may rely on text or SMS messaging providing by third-party providers and you acknowledge and agree that our customer provider partners may send you text or SMS messages for purposes. We do not control these third parties' tracking technologies or how they may be used. If you have any questions about an advertisement or other targeted content, you should contact the responsible provider directly. For information about how you can opt out of receiving targeted advertising from many providers, see "Choices About How We Use and Disclose Your Information" below. ## How We Use Your Information We use information that we collect about you or that you provide to us, including any personal information: * To present our Platform and its contents to you. * To provide you with information, products, or services that you request from us. * To fulfill any other purpose for which you provide it. * To provide you with notices about your account, including expiration and renewal notices. * To carry out our obligations and enforce our rights arising from any contracts entered into between you and us, including for billing and collection. * To notify you about changes to our Platform or any products or services we offer or provide through it. * To allow you to participate in interactive features on our Platform. * To coordinate with third-party service providers to automate the development process of our Platform. * For any other purpose with your consent. We may also use your information to contact you about our own and third-parties' goods and services that may be of interest to you. For more information, see "Choices About How We Use and Disclose Your Information" below. ## Disclosure of Your Information We may disclose aggregated information about our users, and information that does not identify any individual, without restriction. We may disclose personal information that we collect or you provide as described in this privacy policy: * To our subsidiaries and affiliates. * To contractors, service providers, and other third parties we use to support our business. The third parties that process customer data on our behalf are listed on our [Sub-processors](/sub-processors) page. * To a buyer or other successor in the event of a merger, divestiture, restructuring, reorganization, dissolution, or other sale or transfer of some or all of Company's assets, whether as a going concern or as part of bankruptcy, liquidation, or similar proceeding, in which personal information held by Company about our Platform users is among the assets transferred. * To third parties to market their products or services to you if you have not opted out of these disclosures. For more information, see "Choices About How We Use and Disclose Your Information" below. * To fulfill the purpose for which you provide it. * For any other purpose disclosed by us when you provide the information. * With your consent. We may also disclose your personal information: * To comply with any court order, law, or legal process, including to respond to any government or regulatory request. * To enforce or apply our [Terms of Service](https://localops.co/terms) and other agreements, including for billing and collection purposes. * If we believe disclosure is necessary or appropriate to protect the rights, property, or safety of Company, our customers, or others. This includes exchanging information with other companies and organizations for the purposes of fraud protection and credit risk reduction. ## Choices About How We Use and Disclose Your Information We strive to provide you with choices regarding the personal information you provide to us. We have created mechanisms to provide you with the following control over your information: * **Tracking Technologies and Advertising.** You can set your browser to refuse all or some browser cookies, or to alert you when cookies are being sent. To learn how you can manage your Flash cookie settings, visit the Flash player settings page on Adobe's website. If you disable or refuse cookies, please note that some parts of this site may then be inaccessible or not function properly. * **Disclosure of Your Information for Third-Party Advertising.** If you do not want us to share your personal information with unaffiliated or non-agent third parties for promotional purposes, you can opt-out by logging into the Platform and adjusting your user preferences in your account profile, or by sending us an email with your request to [privacy@localops.co](mailto:privacy@localops.co). * **Promotional Offers from the Company.** If you do not wish to have your contact information used by the Company to promote our own or third parties' products or services, you can opt-out by logging into the Platform and adjusting your user preferences in your account profile by checking or unchecking the relevant boxes or by sending us an email stating your request to [privacy@localops.co](mailto:privacy@localops.co). If we have sent you a promotional email, you may send us a return email asking to be omitted from future email distributions. This opt out does not apply to information provided to the Company as a result of a product purchase, warranty registration, product service experience or other transactions. * **Targeted Advertising.** If you do not want us to use information that we collect or that you provide to us to deliver advertisements according to our advertisers' target-audience preferences, you can opt-out by sending us an email stating your request to [privacy@localops.co](mailto:privacy@localops.co). We do not control third parties' collection or use of your information to serve interest-based advertising. However, these third parties may provide you with ways to choose not to have your information collected or used in this way. You can opt out of receiving targeted ads from members of the Network Advertising Initiative ("NAI") on the NAI's website. California residents may have additional personal information rights and choices. Please see "Your California Privacy Rights" below for more information. ## Accessing and Correcting Your Information You can review and change your personal information by logging into the Platform and visiting your account profile page. We may not accommodate a request to change information if we believe the change would violate any law or legal requirement or cause the information to be incorrect. If you delete your User Contributions from the Platform, copies of your User Contributions may remain viewable in cached and archived pages, or might have been copied or stored by other Platform users. Proper access and use of information provided on the Platform, including User Contributions, is governed by our [Terms of Service](https://localops.co/terms). ## Your California Privacy Rights If you are a California resident, California law may provide you with additional rights regarding our use of your personal information. To learn more about your California privacy rights, visit [https://localops.co/ccpa](https://localops.co/ccpa). California's "Shine the Light" law (Civil Code Section § 1798.83) permits users of our App that are California residents to request certain information regarding our disclosure of personal information to third parties for their direct marketing purposes. To make such a request, please send an email to [privacy@localops.co](mailto:privacy@localops.co). California law requires that we provide you with a summary of your privacy rights under the California Online Privacy Protection Act ("COPPA") and the California Business and Professions Code. As required by COPPA, we will provide you with the categories of personal information that we collect through the Platform, and the categories of third party persons or entities with whom such personal information may be shared for direct marketing purposes at your request. California law requires us to inform you, at your request: 1. The categories of personal information we collect and what third parties we share that information with; 2. The names and addresses of those third parties; and 3. Examples of the products marketed by those companies. COPPA further requires us to allow you to control who you do not want us to share that information with. To obtain this information, please send a request by email or physical mail to the address found below. When contacting us, please indicate your name, address, email address, and what personal information you do not want us to share with our marketing partners. The request should be sent to the attention of our legal department, and labeled "California Customer Choice Notice." Please allow 30 days for a response. Also, please note that there is no charge for controlling the sharing of your personal data or requesting this notice. ## International Users & Data Storage Location The Platform is intended for users located worldwide. We make no representation that the Platform is appropriate for use in your country. We understand that we have users from different countries and regions with different privacy expectations, and we try to meet those needs. If you are visiting the Platform from regions with laws governing data collection and use, then please note that you are agreeing to the transfer of your personal information to the United States and the processing and storage of such information in the United States, unless otherwise explicitly stated otherwise wherever applicable within the Platform. By providing your information to the Platform, you consent to any transfer and processing in accordance with this Privacy Policy. However, our practices regarding your personal information will at all times continue to be governed by this Privacy Policy and, if applicable, we will comply with the General Data Protection Regulation and requirements providing adequate protection for the transfer of personal information from the EU/EEA to a third country. We have adopted reasonable physical, technical and organizational safeguards which substantially mirror the various international and state safeguards against accidental, unauthorized or unlawful destruction, loss, alteration, disclosure, access, use or processing of data in our possession. ## Data Retention & Deletion The Platform will retain your information while your account is active and after termination, we may retain certain information unless you delete it or request us to delete it. As such, we do not automatically delete inactive accounts. If you would like to cancel your account or delete your information, you may do so by emailing [privacy@localops.co](mailto:privacy@localops.co). We will retain and use your information as necessary to comply with our legal obligations, resolve disputes, and enforce our agreements, but barring any applicable legal requirements, we will delete your full account profile (within reason) within 30 days of notice. ## Data Security We have implemented measures designed to secure your personal information from accidental loss and from unauthorized access, use, alteration, and disclosure. The safety and security of your information also depends on you. Where we have given you (or where you have chosen) a password for access to certain parts of our Platform, you are responsible for keeping this password confidential. We ask you not to share your password with anyone. We urge you to be careful about giving out information in public areas of the Platform like message boards. The information you share in public areas may be viewed by any user of the Platform. > [!WARNING] > > Unfortunately, the transmission of information via the internet is not completely secure. Although we do our best to > protect your personal information, we cannot guarantee the security of your personal information transmitted to our > Platform. Any transmission of personal information is at your own risk. We are not responsible for circumvention of > any privacy settings or security measures contained on the Platform. ## Children Our Platform is not intended for children. No one under age 18 may provide any information to or on the Platform. We do not knowingly collect personal information from children under 18. If you are under 18, do not use or provide any information on the Platform or through any of its features or downloadable material, register on the Platform, make any purchases through the Platform, use any of the interactive or public comment features of the Platform, or provide any information about yourself to us, including your name, address, telephone number, email address, or any screen name or user name you may use. If we learn we have collected or received personal information from a child under 18 without verification of parental consent, we will delete that information. If you believe we might have any information from or about your child under 18, please contact us at [privacy@localops.co](mailto:privacy@localops.co). California residents under 16 years of age may have additional rights regarding the collection and sale of their personal information. Please see "Your California Privacy Rights" above for more information. ## Changes to Our Privacy Policy It is our policy to post any changes we make to our privacy policy on this page with a notice that the privacy policy has been updated on the Platform home page. If we make material changes to how we treat our users' personal information, we will notify you by email to the email address specified in your account or through a notice on the Platform home page. The date the privacy policy was last revised is identified at the top of the page. You are responsible for ensuring we have an up-to-date active and deliverable email address for you, and for periodically visiting our Platform and this privacy policy to check for any changes. ## Contact Information To ask questions or comment about this privacy policy and our privacy practices, or to register a complaint or concern please contact us at [privacy@localops.co](mailto:privacy@localops.co). # Data security Source: https://docs.localops.co/security LocalOps takes security seriously and is committed to safeguarding your accounts and data with state of the art security controls and best practices. > [!NOTE] > > LocalOps is SOC 2 compliant. To request a copy of our SOC 2 certificate, reach out to your point of contact or email > us at [support@localops.co](mailto:support@localops.co). We share it once you have signed the NDA we provide. **NIST & SOC2 aligned:** Our security controls align with industry standard NIST & SOC2 frameworks and span from hiring, software architecture & software development life cycle, software hosting, configuration & releases on the cloud, disaster recovery and more. LocalOps serves some of the finest growing startups & businesses across US, India & other parts of the world. This document provides an overview and introduction to security controls implemented throughout its platform. > [!TIP] > > Download a PDF version of this doc > [here](https://drive.google.com/file/d/1gveW5KkpB4LA_px7aPxlq1zMrawjrGc8/view?usp=drive_link). Or export it in any > format from > [here](https://docs.google.com/document/d/1ZuwoTlJ3nki4789TK34DAY9__A7-ElceM9_4fkihKSs/edit?usp=drive_link). > [!NOTE] > > This document covers LocalOps SaaS version. You can also run LocalOps in your cloud account for more privacy/control. > Your team can manage the instance (self-hosted) or we can manage them remotely for you (BYOC). Talk with us at > [support@localops.co](mailto:support@localops.co) / [https://go.localops.co/tour](https://go.localops.co/tour) and we can get it running in just a few days. ## Secure cloud infrastructure LocalOps hosts its platform and services in Amazon Web Services, in the US Oregon region. AWS is ISO 27001, PCI DSS Service provider Level 1 and SOC2 compliant cloud provider. ![SOC2](https://mintcdn.com/localops/ARVtqPDOL_f1033h/images/soc2.png?fit=max\&auto=format\&n=ARVtqPDOL_f1033h\&q=85\&s=dcf01e59b81ac75e0e54ad758ef5d19f) ![HIPAA](https://mintcdn.com/localops/ARVtqPDOL_f1033h/images/hipaa.png?fit=max\&auto=format\&n=ARVtqPDOL_f1033h\&q=85\&s=b2133b5ce06ec0a399f956bc06f95a51) ![ISO27001](https://mintcdn.com/localops/ARVtqPDOL_f1033h/images/iso27001.png?fit=max\&auto=format\&n=ARVtqPDOL_f1033h\&q=85\&s=4cf6f3ebed82d1883fb541feb7ddffb5) ![PCI](https://mintcdn.com/localops/ARVtqPDOL_f1033h/images/pci.png?fit=max\&auto=format\&n=ARVtqPDOL_f1033h\&q=85\&s=121d1078b3227c9b2fd8ffa264fe8b7e) * **High Availability and Redundancy:** All systems are designed with high availability and redundancy, as certified by independent third party auditors and certifications. * **24/7 Physical Access Security:** Physical access is safeguarded 24/7 with CCTV surveillance and strict access control policies. * **Network, Compute, and Storage Redundancy:** Assets in the network, compute, and storage layers have high redundancy and availability built in. * **Environmental Safeguards:** Backup power, HVAC systems, fire suppression equipment, flood prevention, and other controls are implemented to safeguard against natural and environmental risks. * **Business Continuity and Disaster Recovery:** Business continuity and disaster recovery procedures are in place to provide quick turnaround and resolutions during disruptions. LocalOps leverages all these security controls in hosting its platform at AWS. See more details about data center security controls implemented in AWS at [https://aws.amazon.com/trust-center/data-center/our-controls/](https://aws.amazon.com/trust-center/data-center/our-controls/) ## Secure software development LocalOps follows secure software development cycle practices while building its platform. 1. **Version Control:** Code versions are managed using Git and hosted privately in Github. Git is the same version control system used by the Linux community in building Linux Kernel which powers most of the internet. 2. **Environment Isolation:** Development, staging and production environments are isolated from each other. 3. **Peer & Automated Code Reviews:** All new features and changes are reviewed by peer engineers and/or AI code review tools to detect errors and security vulnerabilities early in the cycle. 4. **Pre-Release Testing:** All new changes are tested in development and staging environments before getting released in production. 5. **Automated Testing:** Automated tests are run before every release to ensure releases are free of common bugs and vulnerabilities. 6. **No Production Data in Development:** No production data is used during development or testing. 7. **Dependency Vulnerability Monitoring:** We use third party tools like Github Dependabot to continuously monitor for vulnerabilities on third party libraries used in the application. 8. **OWASP Vulnerability Mitigations:** Frameworks & libraries used by our application have built-in mitigations for common OWASP vulnerabilities such as SQLi, XSS, CSRF and others. ## Secure software hosting All our services are hosted and maintained in AWS, by following the below security controls: 1. **Secure networks:** Production environment is hosted in its own logically isolated virtual private network (VPC and subnets). 2. **Private server hosting:** All servers are hosted in private subnets of the VPC, except for those servers that accept requests from clients. 3. **Firewall rules:** Strong firewall rules are implemented to allow only required ports in each of the compute instances that host LocalOps services. 4. **Redundancy:** Servers are hosted in multiple AZs (Availability Zones) for redundancy. 5. **Uptime monitoring:** Service uptime is monitored using third party tools. 6. **Secure deployments:** New software changes are built & deployed securely and automatically by our CI/CD setup. 7. **Resource monitoring:** All servers are monitored for their resource consumption and alerts are set up for any anomalies. 8. **Traffic security:** HTTP/HTTPS Traffic to the software is safeguarded against bots, malicious actors & DDoS attacks using Cloudflare CDN and CloudFront CDN. ## Secure customer data The following security controls are in place to safeguard data in the LocalOps platform: 1. **Isolated Virtual Machines:** Software is hosted in isolated VMs provided by AWS Elastic Compute Cloud. AWS ensures that no two VMs share common memory space. VMs are fully scrubbed after deletion. 2. **Secure Firewall Rules:** Secure firewall rules are implemented to allow only authorized access. 3. **Encryption in Transit:** Encryption is turned on during transit. Data transmitted from the application UI to our web servers is encrypted using HTTPS/TLS 1.2, RSA, and 2048-bit keys at all times. 4. **Encryption at Rest:** Encryption is turned on at rest. All data is encrypted before it is stored in AWS disk volumes. 5. **Encrypted Backups:** Backups are encrypted before they get stored in Amazon S3, and are automatically deleted by AWS after 30 days. 6. **Protection Against OWASP Vulnerabilities:** Incoming HTTP traffic is secured against OWASP vulnerabilities using Cloudflare CDN, CloudFront CDN, and the web framework we use to build services. 7. **Strict Internal Authentication:** All internal data services have strict authentication turned on. 8. **Restricted SSH Access:** SSH access is enabled only for a select few authorized personnel in the company. 9. **Multi-Factor Authentication (MFA):** All access to servers is safeguarded by MFA. 10. **Command Auditing and Logging:** All commands used in the hosting environment are audited and logged. ## Incident response plan Alert rules are configured in all parts of the software stack to detect issues and escalate anomalies to the team. **Recovery Time Objective (RTO):** Services are recovered within 24 hours. 1. **Communication/escalation:** Internal & instant communication tools are active all the time, to communicate, escalate and recover from incidents. 2. **Clear assignments:** Assignments are done within the team to own and recover from specific issues 3. **RCAs:** Root cause analysis is carried out by the assignee(s) 4. **Review/approval:** Fixes are made to software, configuration or infrastructure after internal review & approval from the owners of the system(s). 5. **Post mortems:** Post mortems are conducted post the incident to prevent similar issues in future ## Disaster recovery procedures LocalOps has outlined clear disaster recovery procedures to recover services during major incidents. These procedures are also tested regularly. 1. **Backup Storage:** All backups are stored in Amazon S3. 2. **Geographic Redundancy:** Backups are stored in the US-east while our services are running in the US-west, to mitigate risks of regional failures in the US-west. 3. **Backup Frequency & Security:** Backups are taken and transferred securely to S3, every hour. 4. **Backup Retention:** All backups are kept for 30 days. 5. **Recovery Point Objective (RPO):** Data is restored from the most recent backup that is less than or up to 60mins old. ## Product security Within LocalOps platform and services, all the following security controls are implemented to protect your account logins and data. 1. **Passwordless Logins:** Logins don’t accept passwords at all to eliminate all vulnerabilities that arise out of weak passwords. 2. **Two-Factor Authentication (2FA) & OAuth:** 2FA is the default sign in method for all users using email-based login. Otherwise, OAuth logins powered by Google or Github secure the login process. 3. **Session Expiry:** Login sessions expire after 2 days without use, and every session ends after 7 days at most, however active it is. 4. **Role-Based Access Control (RBAC):** Organization roles (Owner, Admin, Member) control what people can do across your account. Project roles (Member, Maintainer, Read-only) control what they can do in each project, and [protected environments](/environment/protected-environments) limit sensitive environments such as production to the people you choose. See [Understanding roles](/team/understanding-roles). 5. **Audit Logging:** Audit logs record actions taken by users in your LocalOps account. ## Organization security 1. **Employee Screening:** All employees go through relevant reference checks, background checks, and verification before they are onboarded. 2. **NDA and Confidentiality:** All new hires are required to sign a Non-Disclosure Agreement (NDA) as part of their employment contract. 3. **Mandatory 2FA:** Two-Factor Authentication (2FA) is mandatory for all access to all software tools we use. 4. **Security Awareness Training:** The team receives training and orientation on different security vulnerabilities that can occur in code, product, infrastructure, and in general at work—including phishing—to raise awareness and protect all their software access. 5. **Access Auditing:** All access is audited within the organization. For any questions around our security controls, please ping the slack help channel you’re onboarded to or send an email to [security@localops.co](mailto:security@localops.co). # Sub-processors Source: https://docs.localops.co/sub-processors The third-party services LocalOps uses to operate its platform and process customer data. > [!NOTE] > > **Last updated:** September 30, 2026 ## About this page A sub-processor is a third party that LocalOps engages to process customer data on our behalf while delivering the Platform. This page lists our current sub-processors, what each one is used for, and what data it can access. This page complements our [Privacy Policy](/privacy-policy) and [Data security](/security) documentation. It covers the LocalOps SaaS offering. If you run LocalOps in your own cloud account (BYOC or self-hosted), your application data stays in your cloud account and is not processed by the sub-processors below, apart from those needed to operate the LocalOps control plane itself. ## Platform sub-processors These services are part of how the LocalOps platform runs. | Sub-processor | Purpose | Data processed | Location | | - | - | - | - | | Amazon Web Services | Platform hosting, compute, storage and databases | All customer data stored by the LocalOps platform | US (us-west-2, Oregon) | | Cloudflare | DNS, web application firewall and CAPTCHA | Request metadata, IP addresses | Global edge network | | PostHog | Product analytics | Product usage events, account and user identifiers | United States | | Sentry | Crash and error reporting | Error traces, request metadata, account and user identifiers | United States | | GitHub | Source code hosting for the LocalOps platform | LocalOps source code; no customer application data | United States | | Depot | Remote Docker image builds | Customer source code and build artifacts during a build | United States | | Crisp | In-app chat support | Name, email address and the contents of support conversations | European Union | The LocalOps platform does not use any sub-processor other than those listed above. ## Internal business tools LocalOps uses a number of other tools internally to run product development and customer engagement. These tools have no access to customer data and are therefore not sub-processors. ## Changes to this list We update this page whenever we add or remove a sub-processor. To be notified of changes in advance, write to [privacy@localops.co](mailto:privacy@localops.co) and we will add you to our notification list. ## Questions For questions about this list, a copy of our Data Processing Agreement, or to object to a new sub-processor, contact us at [privacy@localops.co](mailto:privacy@localops.co). # Support Source: https://docs.localops.co/support > **[Email Us](mailto:support@localops.co)** > > Reach us via email, at [support@localops.co](mailto:support@localops.co). > **Chat with us** > > Start a quick conversation with our team, from bottom right corner of this page. ### Frequently Asked Questions > **Is there a lock-in? Will environments continue to run after I stop using LocalOps?** > > No. There is no lock-in at all. When you stop using LocalOps, environments are left as they are, in your cloud, for > your team to start managing them. Check [how to eject](/environment/eject) to learn more. > **Can I use any DB for my application?** > > Yes. You are free to provision any database you need for your services. Just add their HOST, PORT, Username and > Password as secrets within your Service settings. They will be passed down as environment variable for your > containers. > **Can I use a Single Page Application (SPA) framework?** > > Yes. You can use any SPA framework to build your Front end. Refer to these guides - [React](/guides/spa/react), > [Angular](/guides/spa/angular), [Ember](/guides/spa/ember), [VueJS](/guides/spa/vue) to learn more. > **Does LocalOps make all of my Application run in multiple cloud providers automatically?** > > Yes, if you have containerised your application and have a Dockerfile for it. However, if you use managed cloud > services such as Amazon S3, you must provide alternate implementations to run in other cloud providers such as GCP > or Azure. > **How do I obfuscate/hide my code if environments run in my customer's cloud account?** > > There is no fool-proof technical way to hide/obfuscate your code. If your service is written in compiled > languages,it helps. Otherwise we'd suggest you to address this legally in your Service agreement with your customer. > **How do I calculate the hosting charges for the resources provisioned in target cloud account?** > > LocalOps tags all cloud infrastructure resources by two standard names. `*-id` and `*-name`. You can locate them in > Environment dashboard. Using these tags, you can filter cloud resources in AWS console, either in Cost management > console or Resource explorer and find out their cost. LocalOps will soon show a monthly cost estimator under each > environment's details page. > **Who pays for the cloud infrastructure resources created by LocalOps?** > > LocalOps provisions environments on cloud accounts you connect. Account administrators of the respective cloud > account have to pay the bills raised by cloud provider. # Audit Log Source: https://docs.localops.co/team/audit-logs In LocalOps, everyone in your account can easily track who created environments in which cloud account and who made deployments. This ensures visibility and transparency within your team. #### Using Audit Logs: You can view all actions initiated across all your cloud accounts or your customers' cloud accounts (AWS/GCP/Azure) and across all cloud regions using Audit logs. ### How It Works: * **Accessing Audit Logs:** Navigate to the "Audit log" tab where you can see all actions done within your account. * **Recording Actions:** We record and display the name of the user who triggered each action and the location from which the action was performed. * Recorded Actions Include: * Project creation and deletion * Environment creation, update, refresh, import and deletion * Service creation, update and deletion, and deployments * Environment and service secret changes * Custom domains added, verified, redeployed and deleted * Backups taken and deleted, and backup settings changes * Cloud connections and git connections connected and removed * Organization role changes, and Owners removed from the organization * People added to or removed from a project, and project role changes * Owner and Admin [restrictions](/team/owner-admin-restrictions) set and lifted * Environments [protected and unprotected](/environment/protected-environments), and environment roles set or removed * **Filtering Options:** You can filter these actions by date to quickly find specific information. * **Across Clouds:** Regardless of which cloud your environment is running in, all actions performed within your LocalOps account are recorded and visible in the Audit Log. #### Note: * **Audit Log Security:** No user can modify or delete entries in the Audit log. * **Access:** Users with any role can view the Audit log. # Invite team members Source: https://docs.localops.co/team/invite-users Invite people to your organization, choose their organization role and project access, and change it later Owners and Admins invite people from organization settings. Each person gets an [organization role](/team/understanding-roles#organization-roles), and organization Members also get a [project role](/team/understanding-roles#project-roles) in each project you add them to. ## Invite someone **1. Open organization members** In the sidebar, under **Organization**, go to **Settings** → **Members** and click **Invite member**. **2. Enter their email** Type their address in **Email**. **3. Pick an organization role** Choose **Admin** or **Member** under **Role**. It starts at **Admin**. To make someone an Owner, invite them first and then [change their role](#change-someones-organization-role). **4. Choose project access (Members only)** For a Member, the **Project access** section lists every project. Pick a role for each project they should join - **Member**, **Maintainer** or **Read-only**. Every project starts at **No access**, and **Set all to** sets the projects shown at once. The footer counts how many projects they'll join. **5. Send it** Click **Send invite**. They get an email with a link to join. When they accept, they join the organization with that role, and as a Member they join each chosen project with its role. > [!NOTE] > > A Member invited with no projects joins the organization but sees no projects until someone adds them to one .Their > sidebar says *"You don't belong to any projects. Contact your admin to get access."* > [!NOTE] > > An invitation stays tied to the person who sent it. If that person is no longer an Owner or Admin when it's accepted, > the invitation stops working and has to be sent again. You can also invite someone straight into a single project from that project's member list - see [invite someone new into the project](/team/project-members#invite-someone-new-into-the-project). ## Manage pending invitations In **Settings** → **Members**, invited people show **Invitation sent** or **Invitation expired**. Click **⋯** → **Actions** on their row to: * **Resend invite** - send the email again, with the same project access * **Copy invite link** - share the link yourself * **Cancel invitation** - withdraw it, including every project it covers ## Change someone's organization role Owners and Admins can change roles from **Settings** → **Members** → **⋯** → **Actions** → **Change role**. Pick the new role and click **Update role**. | Change | What happens | | - | - | | Member → Admin or Owner | They get full access to every project. Their project roles and environment roles are cleared. | | Admin ↔ Owner | Only an Owner can do this. Their project [restrictions](/team/owner-admin-restrictions) are cleared. | | Owner or Admin → Member | They lose full access. The dialog adds a **Project access** section listing every project they're in, each marked **Required** - pick a role for each, then click **Update role**. Their environment roles are cleared. | Only an Owner can make someone an Owner or change an Owner's role. The organization always keeps at least one Owner, so the last Owner can't be changed to Admin or Member. ## Who can do what | Action | Member | Admin | Owner | | - | - | - | - | | Invite people, resend or cancel invitations | - | ✅ | ✅ | | Change someone between Member and Admin | - | ✅ | ✅ | | Make someone an Owner, or change an Owner's role | - | - | ✅ | | [Remove someone from the organization](/team/remove-user) | - | ✅ | ✅ | # Owner and Admin restrictions Source: https://docs.localops.co/team/owner-admin-restrictions Lower an Owner's or Admin's access in a single project or environment, and lift it again Owners and Admins have full access to every project. Sometimes that is more than they need. An Admin who looks after billing shouldn't be one click away from deleting production, and you may want to keep yourself from changing a project by accident. A **restriction** lowers an Owner's or Admin's access in one project, or in one [protected environment](/environment/protected-environments), to Member, Maintainer or Read-only. Everywhere else they keep full access, and they stay an Owner or Admin of the organization. While restricted, they can do exactly what that [project role](/team/understanding-roles#permissions-in-detail) can do. ## Rules | Who | Can restrict | Can lift | | - | - | - | | An Owner or Admin, for **themselves** | Always, to any role - higher or lower than today | Always | | Someone with the Member role in the project (or environment) | Other Owners and Admins | - | | An Owner or Admin with **full access** in the project | Other Owners and Admins | Anyone's restriction | When restricting **someone else**: * The first time, any role can be picked. * If they are already restricted, the role can only be **lowered**. To raise it, an Owner or Admin with full access has to lift the restriction - after which it can be set again. > [!NOTE] > > A restriction can't be used to lock everyone out. The restricted person can always lift their own restriction, and any > Owner or Admin with full access in the project can lift it for them. Owners and Admins can't be removed from a project - restricting them is how you limit them there. ## Restrict yourself in a project 1. Open the project and go to **Settings** → **Members**. 2. Click **⋯** on your own row and choose **Change role**. 3. In **Restrict your access**, pick Member, Maintainer or Read-only and click **Update role**. To change it later, do the same - the dialog is called **Change your restriction**, and you can pick any role, higher or lower. ## Restrict another Owner or Admin in a project You need the Member role in the project, or full access. 1. Go to **Settings** → **Members**. 2. Click **⋯** on their row and choose **Change role**. 3. In **Restrict access**, pick their role and click **Update role**. If they're already restricted, only their current role and lower roles are offered. ## Lift a restriction Click **⋯** on the restricted person's row and choose **Lift restriction**. It takes effect immediately, with no confirmation, and they have full access to the project again. **Lift restriction** works on your own row, and an Owner or Admin with full access can use it on anyone's row. Lifting a project restriction also removes the person's roles in that project's protected environments, so they get full access there too. ## Restrictions in a protected environment The same rules apply inside a [protected environment](/environment/protected-environments), from the environment's **Members** tab: | Action | Menu item | | - | - | | Restrict yourself | **Restrict your access** | | Restrict another Owner or Admin | **Restrict access** | | Change your own restriction (any role) | **Change your restriction** | | Lower someone else's restriction | **Lower restriction** | | Lift a restriction | **Lift restriction** | Restricting someone in a protected environment only changes their access in that environment. Unprotecting the environment removes every restriction in it. ## How restrictions show up In **Settings** → **Members**, a restricted Owner or Admin shows their restricted role with an **Org owner** or **Org admin** badge and a **Restricted** badge. An unrestricted one shows **Full access**. ## Restrictions and organization role changes * **Member → Admin or Owner:** their project roles and environment roles are cleared, so they start with full access everywhere. * **Admin ↔ Owner:** their project restrictions are cleared. Restrictions in protected environments stay until lifted. * **Owner or Admin → Member:** they become a regular Member. You pick their project role in each project they're in, and their environment roles are cleared - add them to protected environments again if they still need them. See [change someone's organization role](/team/invite-users#change-someones-organization-role). # Project members Source: https://docs.localops.co/team/project-members Add people to a project, set their project role, change it, and remove them Each project has its own list of members. Organization Members only see and work in the projects they are added to, with the [project role](/team/understanding-roles#project-roles) they are given there. Owners and Admins don't need adding - they belong to every project. ## Open the member list In the sidebar, under **Project**, go to **Settings** → **Members**. The page is titled **Project Members**. Everyone in the project can see this list. It shows: | Column | What it shows | | - | - | | **User** | The person's name and email | | **Role** | Their project role. Owners and Admins show **Full access** with an **Org owner** or **Org admin** badge. | | **Status** | **Active**, or **Invited** / **Expired** for people who haven't accepted their invitation yet | | **Added at** | When they joined the project | An Owner or Admin who is [restricted](/team/owner-admin-restrictions) in the project shows their restricted role with a **Restricted** badge. > [!TIP] > > Owners and Admins can also see a project's members from **Projects** → the project → **People**. ## Add an existing organization member You need the Member role in the project, or to be an Owner or Admin. **1. Open the dialog** Go to **Settings** → **Members** and click **Add member**. **2. Pick the person** On the **Add existing org member** tab, choose them under **Select member**. Owners and Admins aren't listed - they already have access. **3. Pick their role** Choose a **Project role**. It starts at **Read-only**. **4. Add them** Click **Add to project**. ## Invite someone new into the project Owners and Admins can invite someone who isn't in the organization yet, straight into a project: 1. Go to **Settings** → **Members** and click **Add member**. 2. Open the **Invite new user** tab. 3. Enter their **Email** and pick a **Project role**. 4. Click **Send invite**. They join the organization as a Member, with that role in this project. To invite someone into several projects at once, or as an Admin, [invite them from organization settings](/team/invite-users) instead. ## Change someone's project role You need the Member role in the project, or to be an Owner or Admin. 1. Go to **Settings** → **Members**. 2. Click **⋯** on their row and choose **Change role**. 3. Pick the new role in **Change project role** and click **Update role**. The new role applies straight away, everywhere in the project except [protected environments](/environment/protected-environments) where they have an environment role. On an Owner's or Admin's row, **Change role** restricts them instead. See [Owner and Admin restrictions](/team/owner-admin-restrictions). ## Remove someone from the project You need the Member role in the project, or to be an Owner or Admin. 1. Go to **Settings** → **Members**. 2. Click **⋯** on their row and choose **Remove member**. 3. Confirm with **Continue**. They lose access to the project immediately, including any environment roles they had in it. Their organization membership is not affected. > [!NOTE] > > Owners and Admins can't be removed from a project - the menu shows *"Owners and admins can be demoted but not > removed."* To limit an Owner or Admin in one project, [restrict them](/team/owner-admin-restrictions). To take away > their access everywhere, change their organization role to Member. ## Leave a project Anyone who is an organization Member can leave a project, whatever their project role: click **⋯** on your own row, choose **Remove member** and confirm. ## Cancel a pending invitation Owners and Admins can click **⋯** on an invited person's row and choose **Cancel invitation**. This cancels their whole invitation to the organization, including every project it covers. ## Who can do what here | Action | Read-only | Maintainer | Member | Owner / Admin | | - | - | - | - | - | | See the member list | ✅ | ✅ | ✅ | ✅ | | Add an existing organization member | - | - | ✅ | ✅ | | Change someone's project role | - | - | ✅ | ✅ | | Remove someone from the project | - | - | ✅ | ✅ | | Leave the project | ✅ | ✅ | ✅ | - | | Invite someone new, or cancel an invitation | - | - | - | ✅ | Owners and Admins who are restricted in the project can still invite people and cancel invitations. Adding, changing and removing members needs them to be restricted to Member or not restricted at all. # Remove a user Source: https://docs.localops.co/team/remove-user Remove someone from your LocalOps organization Owners and Admins can remove people from the organization: 1. In the sidebar, under **Organization**, go to **Settings** → **Members**. 2. Find the person and click **⋯** → **Actions** on their row. 3. Choose **Remove member**. 4. Confirm with **Continue**. They lose access immediately - to the organization, every project and every protected environment. > [!NOTE] > > Only an Owner can remove another Owner, and an Owner can't remove themselves. The organization always keeps at least > one Owner. To take someone out of a single project without removing them from the organization, [remove them from the project](/team/project-members#remove-someone-from-the-project) instead. # Understanding roles Source: https://docs.localops.co/team/understanding-roles How organization roles, project roles and protected environments work together to control who can do what in LocalOps. Access in LocalOps works in three layers: 1. **Organization roles** - Owner, Admin or Member - decide what someone can do across your whole LocalOps account. 2. **Project roles** - Member, Maintainer or Read-only - decide what someone can do inside a project. 3. **Protected environments** can give someone a different role on one environment, overriding their project role there. ```mermaid actions={false} theme={null} flowchart TB subgraph org["Organization: Owner, Admin, Member"] subgraph proj["Project: Member, Maintainer, Read-only"] dev["Environment: staging
(uses project roles)"] prod["Environment: production (protected)
environment roles override project roles"] end proj2["Another project
(its own members and roles)"] end classDef default fill:transparent,stroke:#888,stroke-width:1px style org fill:transparent,stroke:#888,stroke-width:1px style proj fill:transparent,stroke:#888,stroke-width:1px ``` ## Organization roles Pick an organization role when you [invite someone](/team/invite-users) to your LocalOps account. ### Owner * Has **unrestricted access** to all features and settings, including billing. * Has full access to every project, unless [restricted](#owners-and-admins-in-a-project) in a specific project. ### Admin * Can do **everything the Owner can**, except manage billing. * Has full access to every project, unless [restricted](#owners-and-admins-in-a-project) in a specific project. * Ideal for team leads who need full operational control without billing oversight. ### Member * Sees **only the projects they've been added to**. * What they can do in each project depends on their [project role](#project-roles). * Can't access projects they aren't part of. Organization-level pages follow the organization role only - project roles and restrictions don't change them. Organization Members can see cloud connections, registries, license tokens, connected GitHub and GitLab accounts, the [audit log](/team/audit-logs) and who's in the organization, but only Owners and Admins can change them. Helm charts and integrations such as Slack are for Owners and Admins only, to view as well as to manage, because Helm charts carry configuration values. Billing is for the Owner. ## Project roles Every organization Member in a project has one of three project roles. | Role | Who it's for | What they can do | | - | - | - | | **Member** | Developers and leads who own the project | Everything in the project: create and change environments and services, manage secrets and members | | **Maintainer** | Developers and on-call engineers who ship | Deploy, roll out, retry, switch branches and read logs - but not change configuration or see secrets | | **Read-only** | Stakeholders, support, auditors | See environments, services and deployments - but not deploy, see secrets or read logs | ### Permissions in detail ✅ allowed · ✕ shown, but greyed out · **Hidden** not shown at all #### Project | Action | Member | Maintainer | Read-only | | - | - | - | - | | See the project - environments, services, deployments, Ops | ✅ | ✅ | ✅ | | See project Settings → General | Hidden | Hidden | Hidden | | Rename or delete the project | Hidden | Hidden | Hidden | #### Project members | Action | Member | Maintainer | Read-only | | - | - | - | - | | See the member list in Settings → Members | ✅ | ✅ | ✅ | | Add an existing organization member | ✅ | ✕ | ✕ | | Change a member's project role | ✅ | ✕ | ✕ | | Remove a member from the project | ✅ | ✕ | ✕ | | Restrict an Owner or Admin in this project | ✅ | ✕ | ✕ | | Change your own role in this project | ✅ | ✕ | ✕ | | Leave the project | ✅ | ✅ | ✅ | | Invite a new user to the organization | ✕ | ✕ | ✕ | | Cancel a pending invite | Hidden | Hidden | Hidden | #### Environments | Action | Member | Maintainer | Read-only | | - | - | - | - | | See environment settings and node groups | ✅ | ✅ | ✅ | | Create an environment | ✅ | ✕ | ✕ | | Change settings, refresh, import or delete | ✅ | ✕ | ✕ | | Change node groups | ✅ | ✕ | ✕ | | Protect an environment and manage its environment roles | ✅ | ✕ | ✕ | | Generate a Helm chart | ✕ | ✕ | ✕ | | Environment CLI (kubeconfig) | ✅ | Hidden | Hidden | Generating a Helm chart is for Owners and Admins only, since a chart carries the environment's configuration values. #### Services | Action | Member | Maintainer | Read-only | | - | - | - | - | | See service settings, scaling, start/stop, IP allowlist, domains, backups | ✅ | ✅ | ✅ | | Create or delete a service | ✅ | ✕ | ✕ | | Change settings, scaling, start/stop, IP allowlist, domains, backups | ✅ | ✕ | ✕ | | Deploy, redeploy or promote | ✅ | ✅ | ✕ | | Cancel a deployment or retry an operation | ✅ | ✅ | ✕ | | Change the git branch | ✅ | ✅ | ✕ | | Operation and deployment logs | ✅ | ✅ | ✕ | | Helm values and `ops.json` | ✅ | Hidden | Hidden | | See secret names | ✅ | ✅ | Hidden | | See secret values | ✅ | Hidden | Hidden | | Add, edit or delete secrets | ✅ | ✕ | Hidden | | Service CLI - regular services | ✅ | ✅ (install, log in, tail logs) | Hidden | | Service CLI - Helm chart services | ✅ | Hidden | Hidden | When an action is greyed out, LocalOps shows "Your role in this project doesn't allow this." The `ops` CLI follows the same roles: `ops logs` needs Maintainer, while `ops connect`, `ops proxy` and `ops update-kubeconfig` need Member. See [who can run which command](/cli/usage#who-can-run-which-command). ### Managing project members Project Members manage who else is in the project, from the project's **Settings → Members**: they add existing organization members, set or change their project role, and remove them. Anyone can leave a project on their own. See [Project members](/team/project-members) for the steps. Inviting someone who isn't in your organization yet, and cancelling pending invites, is done by Owners and Admins. See [Invite team members](/team/invite-users). ## Owners and Admins in a project Owners and Admins have full access to every project. To scale that back in a particular project - say, to keep an Admin from accidentally changing production config - an Owner, Admin or project Member can **restrict** them to Member, Maintainer or Read-only in that project. They then act with that role there. Owners and Admins can't be removed from a project, only restricted. A restricted Owner or Admin still keeps a few organization-level abilities in that project: | Restricted Owner or Admin | Can they? | | - | - | | See project Settings → General | ✅ Yes, but renaming and deleting the project is greyed out | | Invite new users to the organization | ✅ Yes, and cancel pending invites | | Change their own role in the project | ✅ Yes, to any role | | Lift their own restriction | ✅ Yes | | Lift another Owner's or Admin's restriction | ✕ Only an unrestricted Owner or Admin can | | Leave the project | ✕ Owners and Admins stay in every project | Restrictions can only be tightened afterwards. To restrict someone who is already restricted, pick a lower role. To give them more access, lift the restriction instead. See [Owner and Admin restrictions](/team/owner-admin-restrictions) for the full rules, including restrictions on a single protected environment. > [!NOTE] > > A restricted Owner or Admin can lift their own restriction at any time. Restricting is a guard against mistakes, not a > security boundary - to truly limit someone's access, give them the organization Member role instead. ## Protected environments Some environments need tighter control than the rest of the project. Mark an environment as **protected** - production is the usual one - and you can give people an **environment role** on it: Member, Maintainer or Read-only. On a protected environment, a person's environment role **replaces** their project role, whether it's higher or lower. People without an environment role can't see a protected environment at all - it's hidden from them - unless they're an unrestricted Owner or Admin. ```mermaid actions={false} theme={null} flowchart TB start["Someone opens an environment"] --> oa{"Unrestricted
Owner or Admin?"} oa -- "Yes" --> full["Full access"] oa -- "No" --> prot{"Environment
protected?"} prot -- "No" --> projr["Their project role applies
(or their restricted role)"] prot -- "Yes" --> role{"Do they have an
environment role here?"} role -- "Yes" --> envr["Their environment role applies"] role -- "No" --> none["No access
(environment is hidden)"] classDef default fill:transparent,stroke:#888,stroke-width:1px ``` ### Example In the project **Payments**, `production` is protected and `staging` isn't: | Person | Project role | Environment role on `production` | On `staging` | On `production` | | - | - | - | - | - | | Priya | Member | Read-only | Member | Read-only | | Dev | Maintainer | Member (on-call lead) | Maintainer | Member | | Sam | Read-only | - | Read-only | No access | Priya builds freely in staging but can only look at production. Dev normally deploys only, but owns production while on call. Sam has no environment role on production, so production is hidden from them; on staging their project role applies. ### Protect an environment Anyone who can change an environment's settings - unrestricted Owners and Admins, project Members, and Owners or Admins restricted to Member - can protect it. If they don't have full access, they're added to it with their current role, so they keep access. Once it's protected, managing its members needs the Member role in that environment, or full access. 1. Open the environment and click **Protect** at the top of the page, then confirm. 2. Go to the environment's **Members** tab, which appears once it's protected. 3. Add the people who need access to this environment, and pick an environment role for each. Unrestricted Owners and Admins keep full access to protected environments too, unless they've been [restricted in that environment](/team/owner-admin-restrictions#restrictions-in-a-protected-environment). > [!WARNING] > > Unprotecting an environment deletes every environment role in it, Owner and Admin restrictions included. Everyone goes > back to their project role. See [Protected environments](/environment/protected-environments) for adding people, changing their roles and who can do what. ## Related * [Invite team members](/team/invite-users) * [Project members](/team/project-members) * [Owner and Admin restrictions](/team/owner-admin-restrictions) * [Protected environments](/environment/protected-environments) * [Remove a user](/team/remove-user) * [Audit log](/team/audit-logs) # Terms of Service Source: https://docs.localops.co/terms Terms governing your use of the LocalOps platform and services. > [!NOTE] > > **Last updated:** June 6, 2026 LocalOps Inc. is a company incorporated in Delaware and having its registered office at 16192 Coastal Highway, Lewes, Delaware 19958, County of Sussex, USA. LocalOps offers a web-based platform that lets you automate provisioning of cloud infrastructure and environments in the cloud providers you connect. The terms "LocalOps", "We", "Us", or "Our" refer to LocalOps Inc., and the terms "You" and "Your" refer to the licensed users of LocalOps. ## Scope These Terms form a binding and legal agreement between You and LocalOps and govern Your use of the services which can be accessed via [https://console.localops.co/](https://console.localops.co/), [https://lookout.localops.co/](https://lookout.localops.co/) and other related sub-domains and/or mobile applications and/or all of the webpages, subdomains, country level domain variants and subparts of those websites. By checking the 'I Agree' box on our sign-up page, You, either as an individual or, if You are representing an entity, then on behalf of that entity, agree to be bound by these Terms and any other policies included by reference herein. ## Changes to the Terms LocalOps may from time to time make changes or modifications to any portions of these Terms. If such change or modification is likely to affect Your rights, You will be notified in a manner that seems appropriate to LocalOps. Your continued use of the Platform after the expiry of the said notice period will constitute Your acceptance of the modified Terms. If You do not agree to the modified Terms, You may stop using the Services by sending us an account deletion email request, or send us your concerns and enter into a variation agreement (which will be at the discretion of LocalOps). ## License & Restrictions LocalOps grants to You a limited, non-exclusive and non-assignable license to use the Services for Your business purposes, in accordance with these Terms. If You wish to use the Services in any other manner, You may do so only after obtaining an express written consent from LocalOps. ### Trial / Evaluation License Upon Your request, LocalOps may at its discretion grant to You a non-exclusive, non-assignable trial/evaluation license to access its Service for a period of thirty (30) days. This license shall automatically terminate beyond the said period or upon entering into a valid commercial agreement between the parties. ### Commercial License Upon payment of fees detailed in LocalOps' pricing page, You obtain a commercial license to access and use LocalOps Services for Your business purposes. ### Restrictions By using our Services You agree not to: * modify any instance of Cloud Environment with a tool or application not approved by LocalOps; * send or store material containing software viruses, worms, or other harmful computer codes, files, scripts or programs; * transmit or publish any content that infringes any patent, trademark, trade secret, copyright or other proprietary rights of any party; * create a load on servers of LocalOps, abuse the bandwidth of LocalOps, or create unnatural traffic; * use the Services for transmitting or publishing any illegal content; * facilitate any of the uses that are listed as prohibited activities under applicable state, federal or Your local laws. ## Your Obligations You agree to procure and make available all hardware and infrastructure facilities necessary for using the Services. You agree to be solely responsible for obtaining licenses to cloud infrastructure providers (IaaS), third party tools, applications, or APIs to be used by You. LocalOps shall not be liable for Your enablement, access or use of such third-party cloud infrastructure providers, services or applications, including for processing of Your Data by such third parties. Where You require LocalOps to remotely host and maintain Your standard application environments in a cloud infrastructure environment, You shall then provide site, system, and/or cloud account access ("Access") to LocalOps or any party authorized by LocalOps. You understand and agree that Your denial of Access would mean denial of all remote services of LocalOps. You also understand and agree that, where You deny Access, LocalOps cannot be held responsible or liable for any malfunctioning of the Service, non-availability of the services, or breach of these Terms. LocalOps or its personnel will access or make use of Your accounts or systems only for the aforementioned purposes. ## Fees and Payment Terms You agree to pay the fees as detailed in our pricing page or as mutually agreed and included in a separate document signed by the authorized personnel of each party. Where You fail to pay any undisputed invoice beyond fifteen (15) days of due date (including the period of overdue notice), LocalOps will temporarily suspend Your account. Where the invoice becomes due beyond thirty (30) days, LocalOps will terminate all its maintenance & support services and at its discretion terminate and cancel Your agreement with us. In case of a dispute relating to an invoice, both parties agree to settle such dispute in an amicable manner. Failing the foregoing, the parties may approach the courts as agreed under the Miscellaneous section of these Terms. ## Maintenance and Support Terms As part of Your payment of fees, LocalOps will provide standard 9x5 support that will let You report an issue via email and access any Service related documentation. ## Privacy & Data Security LocalOps will not access any of Your Data without first obtaining Your explicit consent. The Data that You provide, submit or that is collected by LocalOps from You shall be stored and/or processed in accordance with LocalOps' online privacy policy accessible at [https://docs.localops.co/privacy-policy](https://docs.localops.co/privacy-policy). ## Proprietary Rights All data, including but not limited to Your application and its source code, that You submit to us for the purpose of receiving services, is considered proprietary to You. You retain the exclusive ownership of such data. The Services along with related documentation, and intellectual property rights relating to such Services, shall belong exclusively to LocalOps. LocalOps does not grant You or any other party the right to use or claim ownership of these proprietary rights, except as expressly permitted in these Terms. No additional rights or licenses are granted beyond what is expressly stated herein. ## Term & Termination ### Term These Terms shall be valid as long as You continue to pay the base fee collected for accessing the Services. ### Termination Either party may terminate this agreement by providing written notice to the other party on the occurrence of any of the following conditions: * in the event that a party is in breach of any of the terms of these Terms and does not cure such breach after thirty (30) days advance written notice from the other party; * a receiver is appointed for a party or its property; * a party makes a general assignment for the benefit of its creditors; * a party commences, or has commenced against it, proceedings under any bankruptcy or insolvency law; or * a party is liquidated or dissolved. ### Post Termination Upon termination, You shall stop using the Service, with an exception to those cloud environments of Your end-users created using the Service. The aforementioned cloud environments shall be terminated in accordance with the agreement terms mutually agreed and executed between You and Your end-users. ## Warranties & Disclaimers > [!WARNING] > > LOCALOPS WARRANTS THAT THE SERVICE WILL PERFORM SUBSTANTIALLY IN ACCORDANCE WITH THE DOCUMENTATION SUPPLIED BY > LOCALOPS. EXCEPT FOR THE LIMITED WARRANTY STATED ABOVE, LOCALOPS MAKES NO WARRANTIES, WHETHER EXPRESS, IMPLIED, OR > STATUTORY REGARDING OR RELATING TO THE SOFTWARE OR THE DOCUMENTATION, OR ANY MATERIALS OR SERVICES FURNISHED OR > PROVIDED UNDER THIS AGREEMENT, INCLUDING SUPPORT. SPECIFICALLY, LOCALOPS DOES NOT WARRANT THAT THE SOFTWARE WILL BE > ERROR FREE OR WILL PERFORM IN AN UNINTERRUPTED MANNER OR THAT ANY DOWNLOADABLE FILES OR INFORMATION WILL BE FREE OF > VIRUSES OR CONTAMINATION OR DESTRUCTIVE FEATURES. TO THE GREATEST EXTENT ALLOWED BY LAW, LOCALOPS SPECIFICALLY > DISCLAIMS ALL IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE (EVEN IF LOCALOPS HAD BEEN > INFORMED OF SUCH PURPOSE) AND NON-INFRINGEMENT WITH RESPECT TO THE SOFTWARE, DOCUMENTATION AND SUPPORT, AND WITH > RESPECT TO THE USE OF ANY OF THE FOREGOING. ## Indemnity LocalOps agrees that it will, at its own expense, defend You in respect of any action brought against You by a third party, and indemnify and hold harmless You against any award of damages and costs in any and all claims, actions or suits alleging that the Service used within the scope of these Terms constitutes an infringement of any valid patent, copyright or other intellectual property rights, provided You give to LocalOps (i) prompt written notice of the claim, (ii) sole control over the defense or settlement, and (iii) reasonable support and cooperation with regard to the defense. The above is LocalOps' sole obligation to You and shall be Your sole and exclusive remedy pursuant to these Terms for all third party claims relating to intellectual property infringements. LocalOps shall have no indemnity obligation for claims of infringement to the extent resulting or alleged to result from: Your use of the Service along with programs not provided by LocalOps; modification of the Service made by a party other than LocalOps; Your failure to install the updates or patches provided by LocalOps; or Your continued use of allegedly infringing software after being notified thereof or after being informed of modifications that would have avoided the alleged infringement. ## Limitation of Liability > [!WARNING] > > UNDER NO CIRCUMSTANCE WILL LOCALOPS BE HELD LIABLE FOR ANY LOSS OR DAMAGE TO YOUR DATA AS A RESULT OF YOUR BREACH OF > ANY OF THESE TERMS. > > UNDER NO CIRCUMSTANCES AND UNDER NO LEGAL THEORY, WHETHER TORT (INCLUDING NEGLIGENCE), PRODUCT LIABILITY, CONTRACT, > OR OTHERWISE, SHALL EITHER PARTY BE LIABLE TO THE OTHER OR ANY OTHER PERSON FOR ANY INDIRECT, SPECIAL, INCIDENTAL, > RELIANCE OR CONSEQUENTIAL DAMAGES, EVEN IF SUCH PARTY SHALL HAVE BEEN INFORMED OF THE POSSIBILITY OF SUCH DAMAGES. > > TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, LOCALOPS' MAXIMUM AGGREGATE LIABILITY AND THAT OF ITS AFFILIATES, > OFFICERS, EMPLOYEES AND AGENTS, RELATING TO THE SOFTWARE / THE SERVICES, WILL BE LIMITED TO AN AMOUNT EQUAL TO THE > FEES PAID BY YOU DURING THE PRECEDING THREE (3) MONTH PERIOD FROM THE DATE ON WHICH SUCH CLAIM AROSE. ## Miscellaneous These Terms shall be the final and binding agreement with regard to Your use of the Services. These Terms may be amended only by a written agreement signed by the duly authorized agents of the parties. These Terms are governed by the laws of the State of Delaware exclusive of its conflict of law provisions. The parties shall be subject to the jurisdiction of the courts in the State of Delaware and waive any inconvenience thereof. If any provision or provisions of these Terms are found to be illegal, invalid or unenforceable, the legality, validity and enforceability of the remaining provisions of these Terms shall not in any way be affected or impaired. Notwithstanding anything to the contrary contained elsewhere, LocalOps shall not be liable for any violation of its obligations caused by circumstances beyond its reasonable control, such as, but not limited to, acts of God, acts of government, epidemic or endemic breakouts, acts of terror or civil unrest, technical failures beyond LocalOps' reasonable control (including, without limitation, inability to access the internet), or acts undertaken by third parties, including without limitation, distributed denial of service attacks. Nothing in this agreement is intended to confer any benefit, right or remedy upon any person other than the parties to this agreement. Neither party may assign or transfer its rights or obligations under this agreement without the prior written consent of the other party, which may not be unreasonably withheld. No joint venture, partnership, employment, or agency relationship exists between You and LocalOps as a result of these Terms or Your use of the Services. ## End of Terms > [!NOTE] > > If You have any questions regarding these Terms, please write to us at > [legal@localops.co](mailto:legal@localops.co). # Environment creation Source: https://docs.localops.co/troubleshoot/create-environment In this article we can go through troubleshoot steps for most commonly faced issues during Environment creation and deletion. ## Infra limit reached AWS imposes limits on the number of resources that can be created for a specific type. For example, by default, only 5 Elastic IPs (EIPs) are allowed per AWS account per region. If this limit is reached, the Environment creation operation may fail with an error indicating that the maximum allowed limit has been reached. To resolve this issue, you can either clean up unused resources in the target AWS account or contact AWS Support to request an increase in the resource limit, explaining your use case. ## Creation Issues If creating infrastructure resources step fails, you can check the operation logs to understand the cause of the failure. Take appropriate actions based on the logs and retry the operation to resolve the issue. Sometimes, infrastructure creation failures may occur due to temporary issues on the AWS side. Retrying the operation often resolves such issues. ## Deletion Issues During environment deletion, you may encounter errors related to AWS resources not being deleted. This can occur if dependent resources are not fully deleted. While AWS typically handles cascading deletes automatically, there are cases where this process fails, leaving dangling resources that prevent deletion of the environment. In such situations, manually delete the resources from your AWS console and retry the deletion operation. Sometimes, delays or glitches on the AWS side can also contribute to deletion failures. Retrying the deletion operation usually resolves these issues. > [!TIP] > > To ensure all resources are properly deleted, use the provided Environment tags to filter AWS resources and confirm > their removal. This helps maintain a clean and efficient AWS environment. # Custom Domain Source: https://docs.localops.co/troubleshoot/custom-domain Setting up custom domains in services lets you configure your own brand's domain. LocalOps enhances security by automatically applying SSL protection to all configured custom domains, ensuring encrypted web traffic by default. ## Common Issues with Adding Custom Domains ### Custom Domain Verification Failure After saving your custom domain, you will receive three CNAME records to add to your domain's DNS settings. It typically takes a few minutes for these DNS settings to propagate, although in some cases, it may take up to 24 hours. If you attempt to verify and deploy the custom domain immediately after saving, you may encounter a "Verification failed" error. In such instances, please wait a few additional minutes and try verification again. ### Incorrect CNAME Records If custom domain verification continues to fail even after waiting, verify that the provided CNAME records are accurately added to your domain's DNS settings. ### Using a Shorter TTL If correctly configured CNAME records still experience delays in verification, consider deleting the existing CNAME records and recreating them with a Time-to-Live (TTL) of 60 seconds. This shorter TTL can expedite the verification process for your custom domain. # BYOC enterprise delivery Source: https://docs.localops.co/use-cases/byoc How to deploy your SaaS service remotely on customer cloud environments ![Your team pushes to GitHub, and the app deploys into each customer's own AWS, GCP or Azure account](https://mintcdn.com/localops/Sq_QSW7HNT7IRdwN/images/use-cases/byoc.svg?fit=max\&auto=format\&n=Sq_QSW7HNT7IRdwN\&q=85\&s=407a7c2cb3816819247db8f2e2c585b0) For SaaS vendors supporting enterprise customers, private deployments—also known as BYOC (Bring Your Own Cloud)—are increasingly common. Enterprises often require applications to be deployed within their own cloud environments for data residency, compliance, or security reasons. LocalOps makes it simple to offer private SaaS deployments without reinventing your internal DevOps processes for each customer. ### What Is a BYOC Deployment? In a BYOC model, your application is installed inside the customer’s own AWS, GCP, or Azure account. You provide the software, but the infrastructure is owned and controlled by the customer. This approach is typically used to meet requirements such as: * Customer data must remain within their account * Isolation from other tenants for compliance * No shared infrastructure with other customers * Support for air-gapped or private-network environments ### How LocalOps Helps LocalOps provides an out-of-the-box solution for provisioning, deploying, and managing your SaaS product inside customer cloud accounts: * **Standardized environments:** Define your infrastructure once (networking, compute, storage, IAM policies) and reuse it across customers. * **Security best practices:** Each environment is provisioned with hardened defaults, reducing the risk of misconfigurations. * **GitOps-compatible:** Your application can be deployed and updated through version-controlled workflows, ensuring consistency and auditability. * **Region-aware provisioning:** Deploy to the customer’s region of choice while maintaining your base configuration and policies. * **Auto-healing and scaling:** Private environments benefit from the same self-managing capabilities as centralized environments. * **Full-stack observability:** Every customer environment comes with built-in monitoring, logging, and alerting—giving you complete visibility into deployments running in their cloud. ### Common Use Cases * Enterprise customers requesting in-account installations for privacy or regulatory reasons * AI/ML workloads where customers want control over GPU usage or data locality * Healthcare or finance verticals requiring strict compliance boundaries ### Outcome Using LocalOps for BYOC allows you to serve high-value enterprise customers without increasing your DevOps burden. You can deliver your SaaS as-a-service—running in their environment—while still maintaining control over the deployment and upgrade process. This helps reduce sales friction, meet compliance needs, and expand into regulated industries without a full rewrite of your infrastructure tooling. ### Overall steps to offer BYOC deployments 1. Sign up for LocalOps account 2. Have the end customer connect their cloud account to LocalOps 3. Spin up a new environment in the customer's cloud 4. Deploy services into the customer's environment 5. Set up a continuous deployment pipeline 6. Repeat steps 2–5 for each new customer #### Sign up Sign up for LocalOps at [https://console.localops.co/signup](https://console.localops.co/signup) #### Connect the customer's cloud account The end customer needs to connect their own AWS, GCP, or Azure account to LocalOps. This grants LocalOps the permissions needed to provision infrastructure on their behalf, within their account. Refer to [Connect cloud account guide](/accounts/aws) > [!TIP] > > Each customer gets their own isolated account connection. LocalOps never shares credentials or infrastructure across > customer accounts. #### Spin up a new environment Once the customer's cloud account is connected, spin up a new environment inside it. This provisions the networking (VPC), compute cluster, and supporting infrastructure required to run your services. To spin up a new environment, refer to this guide - [create environment](/environment/create) #### Deploy services For each service in your product, create a new service in the customer's environment and link it to the relevant GitHub repo and branch. 1. To create a new service, refer to [Create service guide](/environment/services/create) 2. To make deployments on the service, refer to [Deploy service guide](/environment/services/deploy) 3. Repeat steps 1 and 2 for each service in your app—API, workers, frontend, etc. > [!TIP] > > Use a dedicated branch (e.g. `byoc-prod`) for customer deployments so you can control exactly what version each > customer runs, independent of your internal release cycle. #### Set up continuous deployment With services running in the customer's environment, configure auto-deployments so that new commits to the linked branch trigger a build and deploy automatically. This gives you a GitOps-style pipeline to push updates to the customer's environment on your schedule. Each deployment is versioned, auditable, and can be rolled back at any time from the LocalOps console. Refer to [Deploy service guide](/environment/services/deploy) for more details on configuring automatic deployments. ### Get started now > **[Sign up for free](https://console.localops.co/signup)** > > Create your account and connect your cloud to get started. > **[Book a demo call](https://go.localops.co/tour)** > > We'll walk you through the setup personally. > **[Email support](mailto:support@localops.co)** > > Questions? Write to us at [support@localops.co](mailto:support@localops.co). # Single tenant deployments Source: https://docs.localops.co/use-cases/dedicated-infrastructure How to give dedicated isolated infrastructure for specific customers in your cloud ![Your team pushes to GitHub, and the same code deploys to a separate, isolated environment for each customer in your cloud account](https://mintcdn.com/localops/Sq_QSW7HNT7IRdwN/images/use-cases/single-tenant.svg?fit=max\&auto=format\&n=Sq_QSW7HNT7IRdwN\&q=85\&s=4164451285a8dbe1348b9a8e72d509b3) For SaaS companies working with mid-to-large enterprise customers, providing dedicated infrastructure—isolated environments hosted in the vendor's cloud account—offers a strong middle ground between traditional multi-tenant SaaS and full BYOC (Bring Your Own Cloud) deployments. LocalOps enables you to provision and manage dedicated environments for each customer in your own cloud, without the complexity of maintaining one-off stacks manually. ### What Is Vendor-Managed Dedicated Infrastructure? In this model, the SaaS vendor hosts a separate instance of their product for each customer, running on isolated infrastructure within the vendor's cloud account. It's ideal for: * Customers who want data and compute isolation * Regulated industries needing tenant-level segmentation * High-throughput or high-security use cases * Enterprise accounts that prefer not to share infrastructure with other tenants Unlike BYOC, the vendor still owns and manages the cloud account and infrastructure—but each environment is logically and physically isolated. ### How LocalOps Helps LocalOps lets you scale dedicated deployments efficiently by treating each customer environment as a managed, versioned unit: * **Per-customer isolation:** Each environment has its own VPC, compute pool, and databases—ensuring no cross-tenant exposure. * **Automated provisioning:** Environments are created from standardized templates, minimizing time-to-launch and manual effort. * **Lifecycle management:** Easily handle upgrades, patching, and decommissioning across many customer environments. * **Regional customization:** Choose cloud regions based on customer preferences or compliance requirements. * **Operational visibility:** Monitor, log, and manage each customer stack independently with built-in observability. ### Common Use Cases * Premium enterprise plans with dedicated infrastructure promises * Customers requiring enhanced performance guarantees * Deployment blueprints customized per vertical (e.g. finance, healthcare) * SaaS vendors transitioning toward hybrid or regulated markets ### Outcome With LocalOps, offering dedicated infrastructure becomes a repeatable process—not a custom project. You can scale to dozens or hundreds of isolated environments, each tuned to a customer’s needs, while maintaining centralized control and automation. This approach improves customer trust, unlocks new market segments, and reduces churn risk—without bloating your DevOps team. ### Overall steps to spin up a single tenant environment 1. Sign up for LocalOps account 2. Create and connect your AWS/other cloud account 3. Spin up a dedicated environment per customer 4. Deploy services that are part of your software and link their GitHub repo and branch 5. Test the setup 6. Repeat steps 3–5 as you onboard new customers or release updates #### Sign up Sign up for LocalOps at [https://console.localops.co/signup](https://console.localops.co/signup) #### Connect your cloud account Connect your cloud account to LocalOps to provision isolated customer environments in your own infrastructure. Refer to [Connect cloud account guide](/accounts/aws) #### Spin up a dedicated environment Create a separate environment for each customer. Each environment gets its own VPC, compute pool, and databases. To spin up a new environment, refer to this guide — [Create environment](/environment/create) #### Deploy services For each service in your software, create a service and deploy it in the customer environment. 1. To create a new service, refer to [Create service guide](/environment/services/create) 2. To make deployments on the service, refer to [Deploy service guide](/environment/services/deploy) 3. Repeat steps 1 and 2 for each service in your app — app, workers, web, etc. > [!TIP] > > You can use the same GitHub repo and branch across all customer environments — LocalOps manages each environment > independently, so updates roll out consistently without duplicating code. #### Test the setup After adding all services, test them using the app URL. One of your services will be the main entry point of your app. Use its public URL to test the functionality. ### Get started now > **[Sign up for free](https://console.localops.co/signup)** > > Create your account and connect your cloud to get started. > **[Book a demo call](https://go.localops.co/tour)** > > We'll walk you through the setup personally. > **[Email support](mailto:support@localops.co)** > > Questions? Write to us at [support@localops.co](mailto:support@localops.co). # Environment for each developer Source: https://docs.localops.co/use-cases/environment-per-developer Give every developer their own full-stack environment in your cloud, and let them create, deploy, debug and tear it down themselves. ![Each developer pushes their branch to GitHub, and it deploys to their own environment in your cloud account](https://mintcdn.com/localops/Sq_QSW7HNT7IRdwN/images/use-cases/environment-per-developer.svg?fit=max\&auto=format\&n=Sq_QSW7HNT7IRdwN\&q=85\&s=e00de67915d3c07c8046d7a221be3ca3) Shared staging environments become a queue. One developer's half-finished migration breaks another's demo, QA can't tell whose change caused a bug, and someone has to ask the platform team before they can test anything that isn't merged yet. With LocalOps, every developer can have their own environment - a full copy of your stack, in your cloud, running the branch they're working on. Developers manage it themselves, without filing tickets or touching cloud consoles. ### Why one environment per developer * **No waiting.** Developers test their work as soon as it's pushed, instead of waiting for a shared staging slot. * **No stepping on each other.** Each environment has its own network, cluster, databases and secrets. A bad migration or a load test in one environment can't break anyone else's. * **Production-like.** It's the same kind of environment your production runs on - same cloud, same `ops.json`, same security controls - so "works in my environment" means something. * **Easy hand-off.** Product managers, designers and QA get a stable URL to review a feature before it's merged. > [!TIP] > > Need a throwaway copy for every pull request instead? See [Preview pull requests](/use-cases/ephemeral). Preview > services live inside an existing environment and go away when the PR closes. A developer environment belongs to one > developer and stays up as long as they need it. ## What every environment comes with Each developer environment is set up with the same building blocks as production, automatically. Nobody has to install or wire anything up. **Infrastructure** * A dedicated VPC with private and public subnets, and its own Kubernetes cluster * A load balancer and ingress, with a public HTTPS URL for every web service * SSL certificates, issued and renewed automatically * A static outbound IP, so third-party APIs can allowlist the environment * [Auto-scaling](/environment/services/autoscaling) for services that need it **Monitoring stack for fast debugging** * **Logs.** Every container's logs are collected into Loki, searchable in Grafana, and kept for 30 days. No log drains to configure - just print to stdout. See [Logs](/environment/monitoring/logs). * **Metrics.** Prometheus collects CPU, memory, disk and network metrics for every node, pod and service, with pre-built Grafana dashboards. See [Metrics](/environment/monitoring/metrics). * **Grafana.** Each environment gets its own Grafana, on its own HTTPS URL behind a login, opened from the environment's Monitoring tab. Build your own dashboards and [alerts](/environment/monitoring/alerts) in it. * **CLI access.** Stream logs, open a shell or a database console, and forward ports with the [LocalOps CLI](/cli/usage), without `kubectl` or cloud credentials. **Security** * Services, databases and caches in private subnets, with no public IPs * Encryption in transit and at rest * Keyless, least-privilege cloud access for your services - no access keys to manage * Secrets stored in your cloud account and injected only into the services that need them See [Environment security controls](/environment/security) for the full list. **Data and backups** * Databases, caches, queues and buckets you declare in [`ops.json`](/environment/services/ops-json), created fresh for each environment * Backup tooling for the environment's volumes, and automated backups for the databases it creates ## Set it up once An admin does this once. After that, developers serve themselves. 1. **Connect a cloud account.** [Connect an AWS](/accounts/aws) or [GCP](/accounts/gcp) account for developer environments. Keeping them in a separate account from production keeps their cost and blast radius separate too. 2. **Create a project for developer environments.** Put them in their own project, so developers' access is scoped to it. 3. **Invite developers as Members.** [Invite](/team/invite-users) each developer to the project with the [Member role](/team/understanding-roles). Members can create and manage environments and services inside their project, but can't change project settings or see other projects - including production. If production shares a project with developer environments, [protect it](/environment/protected-environments) so only the people you add can see it. 4. **Describe your stack in `ops.json`.** Declare the databases, caches, queues, buckets, init jobs and health checks your services need in [`ops.json`](/environment/services/ops-json) in each repo. Every new environment then gets its own copies automatically, with no manual wiring. ## What developers do themselves ### Spin up their environment From the LocalOps console, a developer [creates an environment](/environment/create) - say `dev-alice` - in the cloud account connected for developer environments, in a region close to them. LocalOps provisions a dedicated network and Kubernetes cluster for it. > [!TIP] > > **New to the team? Clone an environment.** Instead of adding every service by hand, a new developer can clone a > teammate's environment, or one set up earlier. The clone comes with all its services - including Helm chart services - > their secrets, IP allowlists and `ops.json` references, already pointing at the new environment. Then they switch the > services to their own branch and start pushing. ### Add services from their branch They [create a service](/environment/services/create) for each part of the app - web, API, workers, cron jobs - pointing at the repo and the branch they're working on. LocalOps builds each one and creates the cloud resources declared in its `ops.json`, like a fresh database just for this environment. ### Deploy by pushing code Every push to that branch [deploys automatically](/environment/services/deploy). There's no pipeline to write and no one to ask. Developers can also redeploy or roll back from the console. ### Manage config and secrets Developers set environment variables and [secrets](/environment/services/secrets) for their own environment, like a test API key for a payment provider, without affecting anyone else's. ### Debug on their own With the [LocalOps CLI](/cli/usage), developers can work with their environment from the terminal: ```sh theme={null} ops logs --env dev-alice --svc api # stream logs ops connect --env dev-alice --svc api # open a shell in a running container ops connect --env dev-alice --svc api --dep main-db # open a database shell ops proxy --env dev-alice --svc api # forward a port to localhost ``` Each environment also has its own [logs](/environment/monitoring/logs) and [metrics](/environment/monitoring/metrics) dashboards in Grafana. ### Share it Web services get a public HTTPS URL out of the box, so a developer can send a link to QA or a product manager for review. To keep a developer environment private, restrict it to your office or VPN IPs with the web service's IP allowlist. ### Tear it down When the feature ships, the developer [deletes the environment](/environment/delete), and its cloud resources go with it. Spinning up a fresh one later takes the same few steps. > [!NOTE] > > Creating a new environment takes about 20 minutes, since it provisions a dedicated network and cluster. Most teams > keep each developer's environment running and just point its services at new branches, instead of creating one per > feature. ## Keep costs in check * **Right-size services.** Give developer environment services less CPU and memory, and fewer replicas, than production. * **Use spot capacity.** Run developer environment node groups on spot instances. * **Tear down idle environments.** Delete environments nobody is using, and recreate them when needed. * **Track cost per environment.** Use [resource tags](/environment/infra-resources/aws) to find each environment's resources and their cost in your cloud bill. ## Overall steps 1. Admin connects a cloud account and a project for developer environments, and invites developers as Members 2. Teams declare their dependencies in `ops.json` 3. Each developer creates their own environment 4. They add services from their branch and push to deploy 5. They debug with the CLI and dashboards, and share the URL for review 6. They delete the environment when they no longer need it ### Get started now > **[Sign up for free](https://console.localops.co/signup)** > > Create your account and connect your cloud to get started. > **[Book a demo call](https://go.localops.co/tour)** > > We'll walk you through the setup personally. > **[Email support](mailto:support@localops.co)** > > Questions? Write to us at [support@localops.co](mailto:support@localops.co). # Preview pull requests Source: https://docs.localops.co/use-cases/ephemeral How to spin up ephemeral full-stack enviornments to test pull requests in isolation ![Each pull request opened on GitHub gets its own preview service, with its own database, cache and workers, inside your environment](https://mintcdn.com/localops/Sq_QSW7HNT7IRdwN/images/use-cases/preview-pull-requests.svg?fit=max\&auto=format\&n=Sq_QSW7HNT7IRdwN\&q=85\&s=37a33cadd1ea6e35cab5d48025616f45) ## Overview LocalOps can automatically spin up ephemeral/temporary services to run your code, for every pull request your team creates in GitHub. Each copy can be a full-stack spin-off when combined with [ops.json configuration](/environment/services/ops-json). Read on to learn more. [https://www.loom.com/embed/cfc656d1e23343b3acc77f1acff1a209](https://www.loom.com/embed/cfc656d1e23343b3acc77f1acff1a209) ### How it works Create a [new environment](/environment/create) if one doesn't exist. This will create a VPC and EKS cluster to host the ephemeral services. 1. Create a [new service](/environment/services/create) (say, `backend`) in the environment based on a specific Github repo and branch name (say, `main` branch) 2. Turn on "Enable pull request previews" in the service. 3. Create and save the service From now onwards, LocalOps listens for all pull requests created in the above repository and against the branch configured in the service. When a new pull request is raised in the same GitHub repo, from source branch `f-feature-new` targeting the `main` branch, 1. a new copy of the service `backend` is created in the same environment, referred to as "Preview service", with the latest commit of the PR branch as source. This new PR-based service is its own service with secrets, and other configuration copied from the main service. 2. a new comment is posted on the PR page in GitHub containing the public URL for the service and a link to see deployment logs. When the PR is closed or merged, the preview service is automatically deleted from your environment. > [!NOTE] > > For preview environments to work, the github user who is commiting on the pull request branch must be added to your > LocalOps account as a user. And they must have linked their Github profile with LocalOps from inside [Profile settings](https://console.localops.co/profile) ### Preview services For each PR that is open, there will be a new *Preview service* created as per the workflow mentioned above. This is its own service with its own unique name. You can see it in "Services" section of the environment, right next to the main service running based on the target branch. ### Automatic deployments When new commits are pushed to the PR branch, build & deployment steps are triggered automatically on the specific "Preview service" using the latest commit. ### LOPS\_PREVIEW=true For all preview services, LocalOps passes `LOPS_PREVIEW=true` as environment variable so that your code can perform any custom logic suitable for this isolated preview setup. ### Handling dependencies Say your PR is raised from `f-feature-new` branch to get merged into `main` branch. #### Inter service dependencies Say your original service depended on another service in the same environment called "ML API". This dependency may be configured as secrets in the original service `Secrets` section as "ML\_API\_HOST" and "ML\_API\_SECRET". You can update these keys in Secrets section to turn on "**Use in preview environments**" flag. It means that when a new "preview service" is created for on PR, the secrets & their are values from the original service are copied over to the "preview service" as well. When the preview service comes up for any given PR, it comes up with same secrets "ML\_API\_HOST" and "ML\_API\_SECRET\_KEY" set to point at the same "ML API" service. And it retains the dependency as main service. ![Service deps](https://mintcdn.com/localops/RWcRMH72tArZ7dWg/images/preview-service-secrets.png?fit=max\&auto=format\&n=RWcRMH72tArZ7dWg\&q=85\&s=95e3011582d9dab5d31701d75870d8a6) **No limits**: Since preview service is its own service with its own secrets, if you want it to point at a different ML\_API service, you can visit the service > secrets section in LocalOps console, to edit the secret. There is no limit on the dependencies you can configure for the ephemeral preview services. #### Isolated cloud resources Any service can define its cloud resource dependencies (like S3 bucket, SNS topic, RDS instance etc.,) in its [ops.json](/environment/services/ops-json) file. When a new service is created, all those resources defined in `ops.json` are provisioned exclusively for the service, automatically. And when the service is deleted, those resources are deleted automatically. When a new preview service is created specifically for the PR, the same workflow applies. Existing existing `ops.json` configuration in the PR branch is read and new cloud resources are provisioned exclusively for the PR branch and the preview service. The preview service is its own isolated service running the PR branch's code. **preview\_only**: You can define `preview_only` in the dependencies if needed to spin up certain resources only in preview services. Or spin up same resources with different configuration, just for preview services. Say you want to provision a 10GB RDS instance for pull request previews but a 100GB RDS instance during other times. In addition, resources in `ops.json` are configured differently in other ways by LocalOps, for preview services for speed of boot-up and cost savings. Backups, encryption and monitoring are turned off in cloud resources created for preview services. Following services can be defined in `ops.json`: 1. S3 buckets 2. SNS topics 3. SQS queues 4. RDS Database instances - MySQL, Postgres or SQL Server 5. Elastic cache clusters - Memcache or Redis #### Isolated database, cache, queues and workers In addition to above cloud-managed resources, you can also spin any number of these services as ephemeral resources for each PR, to run within the same environment/Kubernetes cluster: 1. Postgres / MySQL database 2. Redis / Memcache servers 3. RabbitMQ queue 4. Workers So for example, you can make a brand new postgres server come up for each PR, in your environment. Just add an `ops.json` in your Github repository that is configured for the main service, if you haven't done it already. In `ops.json`, add `previews` key and list down all dependencies like this: ```json theme={null} { "previews": { "dependencies": { "db": [ { "id": "db", "prefix": "db", "engine": "postgres", "version": "17.5", "exports": { "DB_HOST": "$host", "DB_PORT": "$port", "DB_USER": "$user", "DB_NAME": "$db", "DB_PASS": "$pass" } } ], "cache": [ { "id": "redis", "prefix": "redis", "engine": "redis", "version": "8.0.3", "exports": { "REDIS_HOST": "$host", "REDIS_PORT": "$port" } } ], "queues": [ { "id": "rabbitmq", "prefix": "rabbitmq", "engine": "rabbitmq", "version": "4", "exports": { "QUEUE_HOST": "$host", "QUEUE_PORT": "$port", "QUEUE_VHOST": "$vhost", "QUEUE_USER": "$user", "QUEUE_PASS": "$pass" } } ] }, "workers": [ { "id": "worker", "prefix": "worker", "cmd": "node server.js", "env": { "variable": "value" }, "count": 2 } ] } } ``` Within `exports` key, define all the information you want to export from the resource and inject them as environment variables in your service. All these resources will be created for each PR preview service and get deleted automatically when the PR is closed or merged. Checkout [ops.json docs here](/environment/services/ops-json#ephemeral-databases-and-services-for-pull-request-previews) for more info. #### Isolated cron service `ops.json` is processed exclusively for any given preview service. So any cron configuration defined within the `ops.json` is provisioned exclusively for the preview service. Checkout [cron docs here](/environment/services/ops-json#configuring-cron-service) for more info. #### Third party apps You may use 3rd party services like Slack, Google Apps, and others for Integration, Authentication, Notifications etc., You may define these dependencies in "Secrets" section of the main service. And when the preview services comes up for a given PR, secrets with **"Use in previews"** setting **turned on**, are copied over. When this sharing isn't ideal in your case, you may follow one of the below strategies on a case by case basis. 1. Wait till the preview service comes up first time for a given PR. After it comes up, you may manually create a new instance of your 3rd party app for the purpose of testing it in the preview service. And add its credentials in the preview service's secret section. 2. If the 3rd party allows you to do #1 via their API, you can do so in your application/service boot-up logic, when the preview service comes up. LocalOps passes in `LOPS_PREVIEW=true` in all preview services as in-built environment variable. 3. When there is a possibility to share the same 3rd party integration app/id and create a new redirect URL in the app's settings via their API, you can do the same, as a simplified case of #2 above. LocalOps passes `LOPS_SVC_HOST` environment variable with the latest public url of the service. Talk to us at [support@localops.co](mailto:support@localops.co) and we can come up with alternate strategies to make 3rd party apps work in preview services. ### Get started now > **[Sign up for free](https://console.localops.co/signup)** > > Create your account and connect your cloud to get started. > **[Book a demo call](https://go.localops.co/tour)** > > We'll walk you through the setup personally. > **[Email support](mailto:support@localops.co)** > > Questions? Write to us at [support@localops.co](mailto:support@localops.co). # SaaS environments Source: https://docs.localops.co/use-cases/public-saas How to offer your software as a service on yourdomain.com ![Your team pushes to GitHub, and each branch deploys to test, staging and regional production environments in your cloud account](https://mintcdn.com/localops/Sq_QSW7HNT7IRdwN/images/use-cases/saas-environments.svg?fit=max\&auto=format\&n=Sq_QSW7HNT7IRdwN\&q=85\&s=55b032f00370314ceea03e92b13bf53a) For teams building and operating public SaaS products, managing multiple environments—such as test, staging, and production—alongside regional deployments (e.g., us-east, eu-central) can be challenging to scale and maintain. LocalOps simplifies this with a unified workflow to provision, manage, and automate these environments using GitOps principles and pre-secured defaults. ### Typical Setup A standard public SaaS setup on LocalOps includes: * **Test**: Used for developer testing and quick validation. * **Staging**: Mirrors production for final validation before release. * **Production**: Live environment for customer traffic. * **Regional Variants**: e.g., prod-us, prod-eu, each isolated to comply with local data regulations. All environments can be spun up in minutes. Each environment is provisioned in your own cloud account, with built-in Monitoring stack, auto-scaling, security hardening, and Git-based deployments configured out of the box. ### How LocalOps Helps LocalOps provides a unified workflow to provision, manage, and automate SaaS environments across clouds: * **Standardized environments:** Define your infrastructure once and reuse it across test, staging, production, and regional variants. * **Security best practices:** Each environment is provisioned with hardened defaults, reducing the risk of misconfigurations. * **GitOps-compatible:** Services are deployed and updated through version-controlled workflows, ensuring consistency and auditability. * **Region-aware provisioning:** Spin up environments in any AWS, GCP, or Azure region with the same configuration and policies. * **Auto-healing and scaling:** Environments self-manage with auto-scaling and self-healing built in—no manual intervention needed. * **Full-stack observability:** Every environment comes with built-in monitoring, logging, and alerting out of the box. ### Overall steps to spin up a SaaS environment 1. Sign up for LocalOps account 2. Create and connect your AWS/other cloud account 3. Spin up environments — typically test, staging, and production 4. Deploy services that are part of your software and link their GitHub repo and branch 5. Test the setup 6. Repeat steps 4–5 as you iterate on your code and services #### Sign up Sign up for LocalOps at [https://console.localops.co/signup](https://console.localops.co/signup) #### Connect your cloud account Connect your cloud account to LocalOps to provision environments in your own infrastructure. Refer to [Connect cloud account guide](/accounts/aws) #### Spin up environments Create separate environments for each stage — test, staging, and production. For regional variants, create additional environments such as `prod-us` or `prod-eu`. To spin up a new environment, refer to this guide — [Create environment](/environment/create) #### Deploy services For each service in your software, create a service and deploy it in the environment. 1. To create a new service, refer to [Create service guide](/environment/services/create) 2. To make deployments on the service, refer to [Deploy service guide](/environment/services/deploy) 3. Repeat steps 1 and 2 for each service in your app — app, workers, web, etc. #### Test the setup After adding all services, test them using the app URL. One of your services will be the main entry point of your app. Use its public URL to test the functionality. ### Get started now > **[Sign up for free](https://console.localops.co/signup)** > > Create your account and connect your cloud to get started. > **[Book a demo call](https://go.localops.co/tour)** > > We'll walk you through the setup personally. > **[Email support](mailto:support@localops.co)** > > Questions? Write to us at [support@localops.co](mailto:support@localops.co). # Enable self hosting for enterprise customers Source: https://docs.localops.co/use-cases/self-hosted How to offer self-hosted version of your service to enterprise ![Your team tests the app in your cloud, packages it as a private Helm chart, and each customer installs it with their own license token](https://mintcdn.com/localops/Sq_QSW7HNT7IRdwN/images/use-cases/self-hosted.svg?fit=max\&auto=format\&n=Sq_QSW7HNT7IRdwN\&q=85\&s=c602c454ae864888844b800b5fdc171e) For teams offering self-hosted versions of their software, building & maintaining different version for their service, while allowing customers to consume them at their own cadence can be challenging. While SaaS model keeps all users on the latest version, enterprise companies have their own security policies to define how software must be procured, installed, configured, managed and updated. LocalOps makes distributing self-hosted versions easy for your team, with a modern/Git-ops style distribution pipeline to build, generate and release pre-packaged versions of your service as Kubernetes helm charts. All while not writing Dockerfiles, Yaml Specs, Terraform or Pulumi scripts. ### Overall steps to offer self-hosted version 1. Sign up for LocalOps account 2. Create and connect your AWS/other cloud account 3. Spin up a new environment 4. Deploy services that are part of your software and link their github repo and branch (you could name this branch as `self-hosted`, spun from your `prod` branch.) 5. Test the setup 6. Generate a new private helm chart from the running services 7. Distribute your private helm chart to customer, safely using license tokens 8. Repeat steps 4-7 as you make new changes to your code and services. #### Sign up Sign up for LocalOps at [https://console.localops.co/signup](https://console.localops.co/signup) #### Connect your cloud account Connect your cloud account to LocalOps to create a test environment and test services. Refer to [Connect cloud account guide](/accounts/aws) #### Spin up a new environment To spin up a new environment, refer to this guide - [create environment](http://localhost:3000/environment/create) #### Deploy services For each service you have in your software, spin up a new service and deploy them in environment. 1. To create a new service, refer to [Create service guide](/environment/services/create) 2. To make deployments on the service, refer to [Deploy service guide](http://localhost:3000/environment/services/deploy) 3. Repeat steps 1 and 2, for each service you have in your app - app, workers, web, etc., > [!TIP] > > While using a Github repo and branch for each service, it is ideal to create a new branch called `self-hosted` or > something similar and then use that for the services you spin up. Because you can then manage all self-hosted version > code in its own branch. #### Test the setup After adding all services, test them using the app url. One of our services will be the main entry point of your app. Use its public url to test the functionality. #### Generate private helm charts > [!NOTE] > > Generating and distributing Helm charts, including license tokens and the account's custom domain, is done by an > organization Owner or Admin. See [Understanding roles](/team/understanding-roles#organization-roles). Visit environment dashboard. On the top far right, click on "Generate chart". Give it a new name and new version number and click on generate. This will generate a Kubernetes helm chart for you and it can be used by your customers to install your service in their Kubernetes cluster. Chat with us from below or email us at [support@localops.co](mailto:support@localops.co) and we will guide you here. #### Distribute private helm charts Visit helm charts section (see left sidebar) in LocalOps console. And click on the chart you just generated. Turn on Installation page url and you will see a new url to send it to your customers. > [!TIP] > > In account settings, be sure to set a custom domain. So that your installation url will see your brand domain. In License tokens section, create a new license token, specific to each customer. Distribute both installation url and license token to your customer. They can use these to securely & privately pull and install your service as Kubernetes helm chart. Voila! You just offered your service as a self-hosted version. They can consume the chart and its updates in their cadence from now. ### Get started now > **[Sign up for free](https://console.localops.co/signup)** > > Create your account and connect your cloud to get started. > **[Book a demo call](https://go.localops.co/tour)** > > We'll walk you through the setup personally. > **[Email support](mailto:support@localops.co)** > > Questions? Write to us at [support@localops.co](mailto:support@localops.co).