Create a Fuchsia package repository

The ffx repository commands can create and manage Fuchsia package repositories on the host machine.

Concepts

When a Fuchsia device needs to run new software or update existing software, the device requests and downloads Fuchsia packages from a Fuchsia package server, which is a service that you can run on your host machine. The Fuchsia package server then serves Fuchsia packages from a Fuchsia package repository configured on the host machine.

A Fuchsia package repository is mapped to a directory on the host machine. When handling requests from Fuchsia devices, the Fuchsia package server looks for Fuchsia packages in this directory. If they're found, the package server serves the packages to the devices directly from this directory. Therefore, this directory on the host machine is where you'll want to store your in-development Fuchsia packages for target devices.

Once a new Fuchsia package repository is created, you need to register the package repository to your Fuchsia device (or devices), which permits the device to download Fuchsia packages from this package repository. Fuchsia devices can only download Fuchsia packages from their registered Fuchsia package repositories.

Lastly, you can set up the Fuchsia package server to serve from multiple Fuchsia package repositories on the same host machine, where you may dedicate each package repository for a specific purpose (for instance, to separate stable packages from experimental packages).

Create a package repository

To create and set up a new package repository on your host machine, do the following:

Create a new repository:
```
ffx repository create <REPOPATH>
```
Replace REPO_PATH with the directory path for the new repository.

However, there is no check for existing contents in that directory, so make sure that the directory does not exist before running this command.
(Optional) Set the default name for the repository:
```
ffx repository default set <REPO_NAME>
```
Replace REPO_NAME with the name of a package repository, for example:
```
ffx repository default set my-repo
```
This is typically not needed since the build directory level configuration of ffx already contains the correct value.

After setting the default repository, this command exits silently without output.

Start a Fuchsia package server

To be able to serve packages from Fuchsia package repositories on your host machine, a Fuchsia package server must be running on the machine.

To start a new Fuchsia package server, run the following command:

ffx repository server start --foreground  --repo-path <REPO_PATH>

Replace REPO_PATH with the path to a product bundle on your host machine, for example:

$ ffx repository server start --foreground  --repo-path ~/my-product-bundle

Also, notice that this command starts the package server in the foreground (--foreground). This means the server's log messages will be printed to the terminal window. Alternatively, you can start the package server in the background by using the --background option. In this case, the log messages will be stored in the ${log.dir}/repo-REPO_NAME.log file. For more options, see Start package servers.

Start a Fuchsia package server using a product bundle

To serve packages from an existing product bundle, you need to download the product bundle and start the package server using the product bundle.

Do the following:

View the list of available products:
```
ffx product list
```
Download your desired product bundle:
```
ffx product download <PRODUCT> <DOWNLOAD_DIR>
```
Replace the following:
- PRODUCT_NAME: The product name of your target Fuchsia device.
- DOWNLOAD_DIR: The directory where you want to download the product bundle.
For example:
```
S ffx product download core.x64 ~/Downloads/product-bundles/
```
Start the Fuchsia package server:
```
ffx repository server start --background --product-bundle <DOWNLOAD_DIR>
```
Replace DOWNLOAD_DIR with the directory that contains a product bundle, for example:
```
$ ffx repository server start --background  --product-bundle ~/Downloads/product-bundles
```
You can confirm it is a product bundle directory by checking the presence of product.bundle.json file in the directory. For more information, see Start package servers.

Register a package repository to a Fuchsia device

Once the package server is running, you need to register the server address to the target device.

Do the following:

Enable your Fuchsia device to connect to the new repository:
```
ffx target repository register [-r <REPO_NAME>] --alias fuchsia.com --alias chromium.org
```
Replace REPO_NAME with the name of the repository that you want the Fuchsia device to connect to.

If the -r flag is not specified, the command selects the default repository. For example, thiscommand sets your current Fuchsia device to connect to the default repository (my-repo) at fuchsia.com:
```
$ ffx target repository register --alias fuchsia.com --alias chromium.org
```
After registering the repository, this command exits silently without output.

Verify that the new repository is registered:

ffx target repository list

This command prints output similar to the following:

$ ffx target repository list
REPO                  URL                              ALIASES
fuchsia-pkg://default ["http://10.0.2.2:8083/my-repo"] ["fuchsia.com", "chromium.org"]

Deregister a package repository

To deregister a Fuchsia package repository from the device, run the following command:

ffx target repository deregister [-r <REPO_NAME>]

Replace REPO_NAME with the name of a registered repository, for example:

$ ffx target repository deregister -r my-repo

If the -r option is not specified, the command selects the default repository.

Stop a Fuchsia package server

To stop a running Fuchsia package server, run the following command:

ffx repository server stop

This command prints output similar to the following:

$ ffx repository server stop
server stopped

For more options, see Stop running package servers.