| # Start package servers | |
| The [`ffx repository server`][ffx-repo-server] commands can start and manage | |
| [Fuchsia package servers][fuchsia-package-server] on the host machine. | |
| ## Concepts | |
| Virtually all software running on Fuchsia is collected into Fuchsia packages. | |
| A [Fuchsia package](/docs/concepts/packages/package.md) is a hierarchical | |
| collection of files that provides one or more programs, components, or services | |
| to a Fuchsia system. A Fuchsia package is a term representing a unit of | |
| distribution, though unlike many other package systems, that unit is composed | |
| of parts and is not a single binary BLOB. | |
| Beyond the base packages that comprise the foundation of the Fuchsia platform, | |
| additional packages can be downloaded from a Fuchsia package server. The Fuchsia | |
| package server is an HTTP(S) server managing the Fuchsia packages using TUF (the | |
| update framework). This framework uses cryptographically signed BLOBs to | |
| securely distribute updated packages to a device running Fuchsia. | |
| For developers working with Fuchsia, a package server is provided that | |
| facilitates working with packages that are used as the product foundation and | |
| also overlaying packages compiled locally during the development cycle. | |
| ## Start the package server | |
| The package repository server is controlled by running the subcommands of | |
| [`ffx repository server`][ffx-repo-server]. This server handles | |
| requests for metadata about the available packages and delivers the file blobs | |
| that make up the package contents. | |
| ### Basic command | |
| ```posix-terminal | |
| ffx repository server start | |
| ``` | |
| ### Server Options | |
| #### --address | |
| The address that the package server listens on to for requests. The format | |
| of the address is can be either an IPv4 or IPv6 address. For example, | |
| `[::]:8083` or `127.0.0.1:8083`. Historically, the preferred port for the | |
| package server is `8083`. However there is an effort to improve flexibility by | |
| making the default port `0` indicating to use a dynamic port. The address of | |
| running repository servers is seen by running `ffx repository server list`. | |
| There are no configuration properties influencing the address option. This | |
| option cannot be configured since the port numbers for multiple servers must | |
| be unique. | |
| The motivation for moving to use a dynamic port is to avoid _port in use_ | |
| errors. When running the package server locally with a locally connected device | |
| or emulator, ffx can manage the address of the package server internally. | |
| However, there are cases when a specific network address should be used to serve | |
| packages based on the target device's network connection. For example, when | |
| non-ffx commands are needed for tunneling or firewall configuration, specifying | |
| a port is needed to match configuration in these other tools. | |
| #### --background, --foreground | |
| The execution mode of the package server. These options are mutually exclusive; | |
| only 1 of the execution modes can be used at a time. | |
| * `--background` Indicates the package server will be started in the | |
| background. This is mutually exclusive with `--foreground`. | |
| * `--foreground` Indicates the package server will be started in the foreground. | |
| This is the default mode. This is mutually exclusive with `--background`. | |
| There are no configuration properties that affect the execution mode. The | |
| execution mode of the package server is the source of many, sometimes subtle, | |
| problems with developer workflows. | |
| Developers have preferences, depending on individual circumstances on the UI for | |
| the package server being in the foreground or background. The server behavior is | |
| identical regardless of the processing mode. | |
| These are specific switches vs. an option with enumerated values so insight can | |
| be gathered via command line analytics. Switches appear in the analytics, the | |
| value of an option does not. | |
| Foreground is the default so it is obvious that the package server is | |
| running, and is the most simplistic execution model. | |
| Background is a desirable mode for remote workflows so there can be one remote | |
| terminal window, and with IDEs such as VS Code where the user experience of | |
| switching between multiple terminal windows is not easy. | |
| #### --repo-name | |
| Uniquely identifies the package server by name. If another package server is | |
| running with the same name, the new package server will fail with an error. | |
| The default value is devhost. Primarily for historic reasons. | |
| There is no configuration properties affecting `repo-name`; Server names | |
| must be unique. | |
| #### --repo-path | |
| The path to the root directory of the repository. | |
| This directory can be a repository initialized with `ffx repository create`, or | |
| the root directory of a product bundle. | |
| The default value is undefined, but can be configured. | |
| The configuration property `package.repository.path` can be set. This is the | |
| root directory of the repository. It is expected that this value is set | |
| per-project vs. at the user level since each project probably has a different | |
| repository. | |
| It is also beneficial to set this configuration property so other package | |
| repository tools such as `ffx repository publish` use the same repository path | |
| as the package server. | |
| This value is also referred to by the publishing tools, and represents a core | |
| characteristic of a development project environment. | |
| #### --trusted-root | |
| Path to the root metadata that was used to sign the repository TUF metadata. | |
| This establishes the root of trust for this repository. If the TUF metadata was | |
| not signed by this root metadata, running this command will result in an error. | |
| The default is to use 1.root.json from the repository. | |
| There are no configuration properties that affect `--trusted-root`. | |
| This option is rarely used by developers. | |
| ### Registration options | |
| These are options influencing the server registration on the target devices. | |
| As a developer productivity aide, the package server can register itself on | |
| development devices. The following options affect this registration behavior. | |
| #### --no-device | |
| Disables automatic registration of the server on the target device. | |
| Available only with `--foreground` and `--background`. | |
| This flag is most commonly used when working with multiple devices and multiple | |
| projects and the default behavior is doing the wrong thing. It is also useful | |
| when troubleshooting package resolution. | |
| Eventually to simplify the package serving process, this option will be the | |
| default, or registration removed completely. At this point the automatic | |
| registration workflow would be integrated into other commands. | |
| #### --alias | |
| Identifies a package domain alias for this repository. | |
| This is used when registering the package server on a target device in order to | |
| set up a rewrite rule mapping each `alias` domain to this server. Aliases are | |
| listed for running repositories by running `ffx repository server list`. | |
| This only should be used when there is ambiguity about which package server | |
| should be used to resolve a package. | |
| The default is to not have any alias. | |
| There are no configuration properties affecting `--alias`. | |
| This is commonly used when working on a source code project which produces a | |
| package that must be in the "fuchsia.com" or "chromium.org" domain, but is not | |
| part of the fuchsia source project. | |
| #### --alias-conflict-mode | |
| Defines the resolution mechanism when alias registrations conflict. | |
| Must be either `error-out` or `replace`. | |
| The default behavior is `replace`. | |
| There are no configuration properties affecting `--alias-conflict-mode`. | |
| #### --storage-type | |
| Defines the storage type for packages resolved using this registration. | |
| `persistent` defines that the packages are persisted across reboots. Alternatively, | |
| `ephemeral` defines that the packages are lost when rebooting. | |
| The default is `ephemeral`. | |
| There are no configuration properties affecting `--storage-type`. | |
| There are times when a target device needs to reboot and keep the updated | |
| package rather than reverting to the one contained in the last flash or OTA. | |
| This is especially useful when working with packages that are used during the | |
| startup process. | |
| ## Examples | |
| ### Start the repository in-tree | |
| See [`fx serve` reference](/reference/tools/fx/cmd/serve) for options. As part | |
| of the implementation, `ffx repository server start` is run. | |
| ```posix-terminal | |
| fx serve | |
| ``` | |
| ### Start the repository when using VSCode (single terminal window) | |
| ```posix-terminal | |
| ffx repository server start --background | |
| ``` | |
| or in-tree | |
| ```posix-terminal | |
| fx serve --background | |
| ``` | |
| <!-- Reference links --> | |
| [ffx-repo-server]: /reference/tools/sdk/ffx.md#ffx_repository_server | |
| [ffx-bug]: https://issuetracker.google.com/issues/new?component=1378294&template=1838957 | |
| [fuchsia-package-server]: /docs/concepts/packages/fuchsia_package_server.md |