diff --git a/src/content/docs/containers/local-dev.mdx b/src/content/docs/containers/local-dev.mdx index 1d69b0d8125ee4..912dd9771890a3 100644 --- a/src/content/docs/containers/local-dev.mdx +++ b/src/content/docs/containers/local-dev.mdx @@ -8,22 +8,19 @@ sidebar: You can run both your container and your Worker locally, without additional configuration, by running [`npx wrangler dev`](/workers/wrangler/commands/#dev) (or `vite dev` for Vite projects using the [Cloudflare Vite plugin](/workers/vite-plugin/)) in your project's directory. To develop Container-enabled Workers locally, you will need to first ensure that a -Docker compatible CLI tool and Engine are installed. For instance, you can use [Docker Desktop](https://docs.docker.com/desktop/) -on Mac, Windows, or Linux. +Docker compatible CLI tool and Engine are installed. For instance, you could use [Docker Desktop](https://docs.docker.com/desktop/) or [Colima](https://github.com/abiosoft/colima). -When you run `wrangler dev`, your container image will be built or downloaded. If your -[wrangler configuration](/workers/wrangler/configuration/#containers) sets +When you start a dev session, your container image will be built or downloaded. If your +[Wrangler configuration](/workers/wrangler/configuration/#containers) sets the `image` attribute to a local path, the image will be built using the local Dockerfile. If the `image` attribute is set to a URL, the image will be pulled from the associated registry. Container instances will be launched locally when your Worker code calls to create a new container. This may happen when calling `.get()` on a `Container` instance or -by calling `start()` if `manualStart` is set to `true`. Wrangler will -boot new instances and automatically route requests to the correct local container. +by calling `start()` if `manualStart` is set to `true`. Requests will then automatically be routed to the correct locally-running container. -When `wrangler dev` stops, all associated container instances are stopped, but -local images are not removed, so that they can be reused in subsequent calls to -`wrangler dev` or `wrangler deploy`. +When the dev session ends, all associated container instances should be stopped, but +local images are not removed, so that they can be reused in subsequent builds. :::note If your Worker app creates many container instances, your local machine may not be able to run as many containers concurrently as is possible when you deploy to Cloudflare. @@ -36,7 +33,7 @@ Also note that the `max_instances` configuration option is only enforced when ru ## Iterating on Container code -When you use `wrangler dev`, your Worker's code is automatically reloaded by Wrangler each time you save a change, +When you develop with Wrangler or Vite, your Worker's code is automatically reloaded each time you save a change, but code running within the container is not. To rebuild your container with new code changes, you can hit the `[r]` key on your keyboard, which @@ -44,15 +41,14 @@ triggers a rebuild. Container instances will then be restarted with the newly bu You may prefer to set up your own code watchers and reloading mechanisms, or mount a local directory into the local container images to sync code changes. This can be done, but there is no built-in -mechanism for doing so in Wrangler, and best-practices will depend on the languages and frameworks +mechanism for doing so, and best-practices will depend on the languages and frameworks you are using in your container code. ## Troubleshooting ### Exposing Ports -In production, all of your container's ports will be accessible by your Worker, -so you do not need to specifically expose ports using the [`EXPOSE` instruction](https://docs.docker.com/reference/dockerfile/#expose) in your Dockerfile. +In production, all of your container's ports will be accessible by your Worker, so you do not need to specifically expose ports using the [`EXPOSE` instruction](https://docs.docker.com/reference/dockerfile/#expose) in your Dockerfile. But for local development you will need to declare any ports you need to access in your Dockerfile with the EXPOSE instruction; for example: `EXPOSE 4000`, if you will be accessing port 4000. @@ -70,3 +66,7 @@ connect(): Connection refused: container port not found. Make sure you exposed t You may also see this while the container is starting up and no ports are available yet. You should retry until the ports become available. This retry logic should be handled for you if you are using the [containers package](https://github.com/cloudflare/containers/tree/main/src). + +### Socket configuration - `internal error` + +If you see an opaque `internal error` when attempting to connect to your container, you may need to set the `DOCKER_HOST` environment variable to the socket path your container engine is listening on. Wrangler or Vite will attempt to automatically find the correct socket to use to communicate with your container engine, but if that does not work, you may have to set this environment variable to the appropriate socket path. diff --git a/src/content/docs/workers/wrangler/configuration.mdx b/src/content/docs/workers/wrangler/configuration.mdx index c390e89909c221..1ee305201b75c3 100644 --- a/src/content/docs/workers/wrangler/configuration.mdx +++ b/src/content/docs/workers/wrangler/configuration.mdx @@ -1230,9 +1230,8 @@ You can configure various aspects of local development, such as the local protoc - `container_engine` - - Defaults to `unix:///var/run/docker.sock`. Set this to the socket path your container engine is listening at if you are using another container tool besides Docker, such as `colima`, or if your Docker engine is configured to listen at a path other than `unix:///var/run/docker.sock`. You can also set this via the environment variable `WRANGLER_DOCKER_HOST`. - -Example: + - Used for local development of [Containers](/containers/local-dev). Wrangler will attempt to automatically find the correct socket to use to communicate with your container engine. If that does not work (usually surfacing as an `internal error` when attempting to connect to your Container), you can try setting the socket path using this option. You can also set this via the environment variable `DOCKER_HOST`. + Example: diff --git a/src/content/docs/workers/wrangler/system-environment-variables.mdx b/src/content/docs/workers/wrangler/system-environment-variables.mdx index 670f35b46afc14..14eff0b92d38b6 100644 --- a/src/content/docs/workers/wrangler/system-environment-variables.mdx +++ b/src/content/docs/workers/wrangler/system-environment-variables.mdx @@ -3,10 +3,9 @@ pcx_content_type: configuration title: System environment variables head: [] description: Local environment variables that can change Wrangler's behavior. - --- -import { Render, Type, MetaInfo } from "~/components" +import { Render, Type, MetaInfo } from "~/components"; System environment variables are local environment variables that can change Wrangler's behavior. There are three ways to set system environment variables: @@ -25,62 +24,44 @@ To set different system environment variables for each environment, create files Wrangler supports the following environment variables: +- `CLOUDFLARE_ACCOUNT_ID` + - The [account ID](/fundamentals/account/find-account-and-zone-ids/) for the Workers related account. +- `CLOUDFLARE_API_TOKEN` + - The [API token](/fundamentals/api/get-started/create-token/) for your Cloudflare account, can be used for authentication for situations like CI/CD, and other automation. -* `CLOUDFLARE_ACCOUNT_ID` - - * The [account ID](/fundamentals/account/find-account-and-zone-ids/) for the Workers related account. - -* `CLOUDFLARE_API_TOKEN` - - * The [API token](/fundamentals/api/get-started/create-token/) for your Cloudflare account, can be used for authentication for situations like CI/CD, and other automation. - -* `CLOUDFLARE_API_KEY` - - * The API key for your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_EMAIL=`. - -* `CLOUDFLARE_EMAIL` - - * The email address associated with your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_API_KEY=`. - -* `WRANGLER_SEND_METRICS` +- `CLOUDFLARE_API_KEY` + - The API key for your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_EMAIL=`. - * Options for this are `true` and `false`. Defaults to `true`. Controls whether Wrangler can send anonymous usage data to Cloudflare for this project. You can learn more about this in our [data policy](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler/telemetry.md). +- `CLOUDFLARE_EMAIL` + - The email address associated with your Cloudflare account, usually used for older authentication method with `CLOUDFLARE_API_KEY=`. -* `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_` +- `WRANGLER_SEND_METRICS` + - Options for this are `true` and `false`. Defaults to `true`. Controls whether Wrangler can send anonymous usage data to Cloudflare for this project. You can learn more about this in our [data policy](https://github.com/cloudflare/workers-sdk/tree/main/packages/wrangler/telemetry.md). - * The [local connection string](/hyperdrive/configuration/local-development/) for your database to use in local development with [Hyperdrive](/hyperdrive/). For example, if the binding for your Hyperdrive is named `PROD_DB`, this would be `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_PROD_DB="postgres://user:password@127.0.0.1:5432/testdb"`. Each Hyperdrive is uniquely distinguished by the binding name. +- `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_` + - The [local connection string](/hyperdrive/configuration/local-development/) for your database to use in local development with [Hyperdrive](/hyperdrive/). For example, if the binding for your Hyperdrive is named `PROD_DB`, this would be `WRANGLER_HYPERDRIVE_LOCAL_CONNECTION_STRING_PROD_DB="postgres://user:password@127.0.0.1:5432/testdb"`. Each Hyperdrive is uniquely distinguished by the binding name. -* `CLOUDFLARE_API_BASE_URL` +- `CLOUDFLARE_API_BASE_URL` + - The default value is `"https://api.cloudflare.com/client/v4"`. - * The default value is `"https://api.cloudflare.com/client/v4"`. +- `WRANGLER_LOG` + - Options for Logging levels are `"none"`, `"error"`, `"warn"`, `"info"`, `"log"` and `"debug"`. Levels are case-insensitive and default to `"log"`. If an invalid level is specified, Wrangler will fallback to the default. Logs can include requests to Cloudflare's API, any usage data being collected, and more verbose error logs. -* `WRANGLER_LOG` +- `WRANGLER_LOG_PATH` + - A file or directory path where Wrangler will write debug logs. If the path ends in `.log`, Wrangler will consider this the path to a file where all logs will be written. Otherwise, Wrangler will treat the path as a directory where it will write one or more log files using a timestamp for the filenames. - * Options for Logging levels are `"none"`, `"error"`, `"warn"`, `"info"`, `"log"` and `"debug"`. Levels are case-insensitive and default to `"log"`. If an invalid level is specified, Wrangler will fallback to the default. Logs can include requests to Cloudflare's API, any usage data being collected, and more verbose error logs. - -* `WRANGLER_LOG_PATH` - - * A file or directory path where Wrangler will write debug logs. If the path ends in `.log`, Wrangler will consider this the path to a file where all logs will be written. Otherwise, Wrangler will treat the path as a directory where it will write one or more log files using a timestamp for the filenames. - -* `FORCE_COLOR` - - * By setting this to `0`, you can disable Wrangler's colorised output, which makes it easier to read with some terminal setups. For example, `FORCE_COLOR=0`. - -* `WRANGLER_DOCKER_HOST` - - * Defaults to `unix:///var/run/docker.sock`. Set this to the socket path your container engine is listening at if you are using another container tool besides Docker, such as `colima`, or if your Docker engine is configured to listen at a path other than `unix:///var/run/docker.sock`. - You can also set this via `container_engine` config option. +- `FORCE_COLOR` + - By setting this to `0`, you can disable Wrangler's colorised output, which makes it easier to read with some terminal setups. For example, `FORCE_COLOR=0`. * `WRANGLER_HTTPS_KEY_PATH` - - * Path to a custom HTTPS certificate key when running `wrangler dev`, to be used with `WRANGLER_HTTPS_CERT_PATH`. + - Path to a custom HTTPS certificate key when running `wrangler dev`, to be used with `WRANGLER_HTTPS_CERT_PATH`. * `WRANGLER_HTTPS_CERT_PATH` + - Path to a custom HTTPS certificate when running `wrangler dev`, to be used with `WRANGLER_HTTPS_KEY_PATH`. - * Path to a custom HTTPS certificate when running `wrangler dev`, to be used with `WRANGLER_HTTPS_KEY_PATH`. - - +- `DOCKER_HOST` + - Used for local development of [Containers](/containers/local-dev). Wrangler will attempt to automatically find the correct socket to use to communicate with your container engine. If that does not work (usually surfacing as an `internal error` when attempting to connect to your Container), you can try setting the socket path using this environment variable. ## Example `.env` file @@ -100,8 +81,8 @@ WRANGLER_LOG_PATH=../Desktop/my-logs/my-log-file.log The following variables are deprecated. Use the new variables listed above to prevent any issues or unwanted messaging. -* `CF_ACCOUNT_ID` -* `CF_API_TOKEN` -* `CF_API_KEY` -* `CF_EMAIL` -* `CF_API_BASE_URL` +- `CF_ACCOUNT_ID` +- `CF_API_TOKEN` +- `CF_API_KEY` +- `CF_EMAIL` +- `CF_API_BASE_URL`