diff --git a/blog/2025-03-26-deploying-defang-with-defang-part-2.md b/blog/2025-03-26-deploying-defang-with-defang-part-2.md
index 3a30d3da8..729ee35b8 100644
--- a/blog/2025-03-26-deploying-defang-with-defang-part-2.md
+++ b/blog/2025-03-26-deploying-defang-with-defang-part-2.md
@@ -45,14 +45,14 @@ Some things we had to change:
 ```yaml
     domainname: defang.io
     networks:
-      public:
+      default:
         aliases:
           - www.defang.io
 ```
 
 One other hiccup was that we used to do www to non-www redirects using S3. There are a few ways to switch that up, but for the time being we decided to use Next.js middleware.
 
-Pretty soon after that, the site was up and running in an AWS account—with TLS, DNS, and both the `www` and root domains automatically configured. Pretty straightfoward! 
+Pretty soon after that, the site was up and running in an AWS account—with TLS, DNS, and both the `www` and root domains automatically configured. Pretty straightfoward!
 
 ---
 
diff --git a/docs/concepts/compose.md b/docs/concepts/compose.md
index a09e17b00..ab8edb5ac 100644
--- a/docs/concepts/compose.md
+++ b/docs/concepts/compose.md
@@ -6,8 +6,8 @@ sidebar_position: 150
 
 # Compose
 
-Defang allows you to use `compose.yaml` files to deploy your application to the cloud. 
-The `compose.yaml` file is a simple way to define and run multi-container applications. 
+Defang allows you to use `compose.yaml` files to deploy your application to the cloud.
+The `compose.yaml` file is a simple way to define and run multi-container applications.
 This file format may look familiar to you if you've used [Docker](https://docker.com).
 
 The [Compose Specification](https://github.com/compose-spec/compose-spec/blob/main/spec.md#compose-file) lets you define a platform-agnostic application designed as a set of containers which are configured to run together with shared resources. These applications may be destined for any [OCI](https://opencontainers.org/) Container Runtime. Defang does the heavy lifting to deploy to your favourite cloud platform using this file.
@@ -19,20 +19,19 @@ You can create a `compose.yaml` file in the root of your project, or use the [`d
 When you run `defang compose up`, Defang will read your `compose.yaml` file and [deploy](./deployments.md) the services named in that file to the cloud.
 
 ## Example of a Compose File
-Here is a basic `compose.yaml` file that contains all the required properties for deployment in Defang. 
+Here is a basic `compose.yaml` file that contains all the required properties for deployment in Defang.
 
 ```yaml
 services:
   service-example:
     image: nginx:latest # use one of: image (shown on this line) or build (shown below)
-    # build: 
+    # build:
     #   context: .
     #   dockerfile: Dockerfile
-  ports: 
-    - mode: ingress # specify ports to expose
-      target: 8080
-      published: 8080 # this is useful for running locally
-        
+    ports:
+      - mode: ingress # specify ports to expose
+        target: 8080
+        published: 8080 # this is useful for running locally
 ```
 
 ## Compose Top-level Properties
@@ -41,7 +40,7 @@ Here are a list of top-level properties of the [Compose specification](https://d
 ### `services`
 (Required)
 
-The services defined in your application. 
+The services defined in your application.
 
 ```yaml
 services:
@@ -49,18 +48,18 @@ services:
     # add service-level properties here
 ```
 
-:::info 
+:::info
 Defang identifies a service based on your username, project name, and the service name you've defined under the `services` property. See our [Services](/docs/concepts/services) page for more about how Defang resolves service names.
 :::
 
 ### `networks`
 (Optional)
 
-The networks defined in your application. This is commonly added together with a [service-level `networks`](#networks-1) property. 
+The networks defined in your application. This is commonly added together with a [service-level `networks`](#networks-1) property.
 
 ```yaml
 networks:
-  public: 
+  default: # the "default" network is always created even if not specified
 ```
 
 See our [Networking](/docs/concepts/networking) page for more.
@@ -76,7 +75,7 @@ The volume mounts for a container, reusable across services. This feature is not
 ```
 
 :::warning
-Defang does not support the `secrets` top-level property. Please read our [Configuration](/docs/concepts/configuration) page for more. 
+Defang does not support the `secrets` top-level property. Please read our [Configuration](/docs/concepts/configuration) page for more.
 :::
 
 ## Compose Service-level Properties
@@ -86,14 +85,14 @@ Here are a list of service-level properties of the [Compose specification](https
 Service-level means inside your `service`. A service-level property called `build` would look like:
 ```yaml
 service:
-    build: ...
+  build: ...
 ```
 
 Note that in your Compose file, you will need a top-level property called `services` to contain all of your services. For example:
 ```yaml
 services:
-    service:
-        build: ...
+  service:
+    build: ...
 ```
 :::
 
@@ -103,9 +102,9 @@ services:
 The [build configuration](https://github.com/compose-spec/compose-spec/blob/main/build.md). This property describes how to create an OCI container for this service.
 
 ```yaml
-build:
-  context: .
-  dockerfile: ./Dockerfile
+    build:
+      context: .
+      dockerfile: ./Dockerfile
 ```
 
 ### `image`
@@ -114,7 +113,7 @@ build:
 [This property](https://github.com/compose-spec/compose-spec/blob/main/05-services.md#image) describes the image from which your container should start.
 
 ```yaml
-image: nginx:latest
+    image: nginx:latest
 ```
 
 ### `ports`
@@ -123,23 +122,23 @@ image: nginx:latest
 The ports to expose. The default port mode is `ingress`.
 
 ```yaml
-ports:
-  - mode: ingress
-    target: 80
-    published: 80
+    ports:
+      - mode: ingress
+        target: 80
+        published: 80
 ```
 
 :::info
-Defang ignores `published` ports in production. As such, it is common to make `target` and `published` ports the same when using Defang. However, it can be useful to include a `published` port for local development, such as Docker.  
+Defang ignores `published` ports in production. As such, it is common to make `target` and `published` ports the same when using Defang. However, it can be useful to include a `published` port for local development, such as Docker.
 :::
 
 ### `command`
 (Optional)
 
-The command which will be run to start your service. If left out, the command from the Docker image will be used.  
+The command which will be run to start your service. If left out, the command from the Docker image will be used.
 
 ```yaml
-command: nginx -g 'daemon off;'
+    command: nginx -g 'daemon off;'
 ```
 
 ### `deploy`
@@ -148,21 +147,21 @@ command: nginx -g 'daemon off;'
 The [Deploy Specification](https://github.com/compose-spec/compose-spec/blob/main/deploy.md) describes the runtime constraints and requirements for how your services will be deployed and managed across different environments (e.g. memory reservations, replicas, number of CPUs, etc.).
 
 ```yaml
-deploy:
-  replicas: 1
-  reservations:
-    cpus: '0.5'
-    memory: 256M
+    deploy:
+      replicas: 1
+      reservations:
+        cpus: '0.5'
+        memory: 256M
 ```
 
 ### `depends_on`
 (Not yet supported)
 
-This property describes startup dependencies between services. This feature is currently unsupported by Defang, but can be useful in local developments such as Docker. 
+This property describes startup dependencies between services. This feature currently has limited supported by Defang, but can be useful in local development with Docker.
 
 ```yaml
-# depends_on: 
-#   - db
+    # depends_on:
+    #   - db
 ```
 
 ### `environment`
@@ -170,12 +169,12 @@ This property describes startup dependencies between services. This feature is c
 
 The environment variables to set.
 ```yaml
-environment:
-  DATABASE_USER: someuser
+    environment:
+      DATABASE_USER: someuser
 ```
 :::info
 For sensitive environment variables (or secret values), you should list the variable's name with a blank or `null` value, and then securely set their actual value with `defang config` in the CLI. See our [Configuration page](/docs/concepts/configuration) for more.
- 
+
  For example:
 ```yaml
   - DATABASE_USER=someuser # env var loaded with this literal value
@@ -191,54 +190,55 @@ For sensitive environment variables (or secret values), you should list the vari
 When using Defang, your Compose file must have a healthcheck if you want to expose an `ingress` port—even if your Dockerfile already contains one.
 
 :::note
-`curl` is commonly used for containers with an Ubuntu-based image, and `wget` is used for containers with an `alpine`-based image. 
+`curl` is commonly used for containers with an Ubuntu-based image, and `wget` is used for containers with an `alpine`-based image.
 :::
 
 ```yaml
-healthcheck:
-  test: ["CMD", "curl", "-f", "http://localhost:8080/"]
-  interval: 30s
-  timeout: 90s
-  retries: 3
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/"]
+      interval: 30s
+      timeout: 90s
+      retries: 3
 ```
 
 or
 
 ```yaml
-healthcheck:
-  test: ["CMD", "wget", "--spider", "http://localhost:8080/"]
-  interval: 30s
-  timeout: 90s
-  retries: 3
+    healthcheck:
+      test: ["CMD", "wget", "--spider", "http://localhost:8080/"]
+      interval: 30s
+      timeout: 90s
+      retries: 3
 ```
 
 ### `networks`
 (Optional)
 
-The network configuration. Can be `public`, where Defang will assign a public IP address, or `private`, in which Defang will not. To avoid warnings, add this to the [top-level `networks`](#networks) property as well. 
+The service network configuration. By default, Compose will add services to the `default` network, which has external connectivity.
+You can also add services to private networks. To avoid warnings, you should add them to the [top-level `networks`](#networks) property as well.
 
 ```yaml
-networks:
-  public: 
+    networks:
+      default: # when not specified, services are assigned to the "default" network
 ```
 
 You can also assign an alias for a network by using `aliases`, as seen below:
 ```yaml
-networks:
-  public: 
-    aliases:
-      - app
+    networks:
+      default:
+        aliases:
+          - app
 ```
- 
+
 See our [Networking](/docs/concepts/networking) page for more.
- 
+
 ### `restart`
 (Optional, but highly recommended)
 
-The restart mode for a container. Defaults to `unless-stopped` unless otherwise specified. 
+The restart mode for a container. Defaults to `unless-stopped` unless otherwise specified.
 
 ```yaml
-restart: unless-stopped
+    restart: unless-stopped
 ```
 
 ### `volumes`
@@ -247,6 +247,6 @@ restart: unless-stopped
 The volume mounts for a container, specific to a service. This feature is not currently supported by Defang.
 
 ```yaml
-# volumes:
-#  - "./backend:/app"
+    # volumes:
+    #  - "./backend:/app"
 ```
diff --git a/docs/concepts/networking.mdx b/docs/concepts/networking.mdx
index 6b3c5cd99..f609f42fe 100644
--- a/docs/concepts/networking.mdx
+++ b/docs/concepts/networking.mdx
@@ -1,5 +1,5 @@
 ---
-title: Networking    
+title: Networking
 description: Defang helps you safely configure your services' networking.
 sidebar_position: 300
 ---
@@ -8,43 +8,102 @@ import TabItem from '@theme/TabItem';
 
 # Networking
 
-Defang configures Security Groups, deploys applications to a private subnet and uses an Application Load Balancer to route traffic to your services from the public internet only when required.
+By default, Defang configures your application's networking and security groups to follow secure best practices.
+We also configure load-balancers and public IP addresses when appropriate. The following sections describe how to configure different network and security group topologies.
 
 :::tip
-This page is about internal networking only. If you want to configure your services to be accessible from the public internet, check the [Domains page](./domains.mdx).
+This page is about complex networking. If you want to configure your services to be accessible from the public internet, check the [Domains page](./domains.mdx).
 :::
 
-## Internal Communication
+## Networks
 
-You can expose ports in your service definition to allow other services to communicate with it. Similar to public communication, you can use the `ports` section of your service definition, but set the `mode` to `host` instead of `ingress` to allow other services to communicate with it through the internal network.
+The Compose spec has a notion of [networks](https://github.com/compose-spec/compose-spec/blob/main/06-networks.md). By default, each service gets added to the `default` network.
+Services in the `default` network can have public IPs. Services in any other network will be in a private subnet.
+These services cannot be reached from outside the network, but they can still make network requests to the public internet.
 
-### Sample Configuration
+```yaml
+services:
+  frontend:
+    build: ./fe
+    ports:
+      - 80 # load-balanced, ie. mode: ingress
+    networks:
+      default:
+      private:
+
+  backend:
+    build: ./be
+    ports:
+      - mode: host # no load balancer
+        target: 8080
+    networks:
+      private:
+
+networks:
+  default:
+  private:
+    internal: true # no egress
+```
+
+### Public Services
+
+By default, services will be in the `default` network. By default these services are not accessible directly, but may be accessed through a public load-balancer, ie. exposed ports default to `mode: ingress`:
 
-<Tabs>
-  <TabItem value="compose" label="Compose" default>
 ```yaml
 services:
-    # [...]
-    service1:
-      ports:
-        - mode: host
-          target: 3000	
-          app_protocol: http
+  web:
+    networks:
+      default: # this is the default, so no need to specify
+    ports:
+      - 80:80 # Defang will use a public load-Balancer
 ```
-  </TabItem>
-  <TabItem value="pulumi" label="Pulumi">
-```typescript
-const service = new defang.DefangService("service1", {
-    // [...]
-    ports: [{
-        target: 3000,
-        mode: "host",
-        protocol: "http",
-    }],
-});
+
+If you want a service to have a public IP address, ensure it's in the `default` network (the default) and
+set the port to `mode: host`:
+
+```yaml
+services;
+  web:
+    ports:
+      - target: 80
+        mode: host # Defang will assign a public IP
+```
+
+### Private Services
+If you want a service with exposed ports to not be accessible from the public internet, create a private network:
+
+```yaml
+services:
+  web: # this service can receive public traffic and communicate to private services
+    ports:
+      - 80
+    networks:
+      default:
+      private:
+  db: # this service can only receive traffic from other services in the same network
+    ports:
+      - 1234
+    networks:
+      private:
+networks:
+  private: # any network that's not "default" is considered private
+```
+
+The service's hostname will be the same as the service's name, in this case `db`.
+
+## Hostname Aliases
+
+By using network aliases, a service can be made available at multiple hostnames.
+
+```yaml
+services:
+  web:
+    domainname: example.com
+    networks:
+      default:
+        aliases:
+          - www.example.com # a public alias
 ```
-  </TabItem>
-</Tabs>
 
 ### Internal DNS
 
@@ -57,10 +116,12 @@ Internal communication between services in the Defang Playground follows the fol
 ```
 http://<username>-<service-name>:<port>
 ```
+
+The Defang CLI applies the `<username>` prefix when it detects service names in the values of environment variables.
   </TabItem>
   <TabItem value="byoc" label="BYOC">
 Internal communication between services in Defang BYOC follows the following pattern:
-  
+
 ```
 http://<service-name>:<port>
 ```