From 7cb75049ae053db1d2faf2741bc8f6d4d7626dbd Mon Sep 17 00:00:00 2001 From: Tiexin Guo Date: Tue, 11 Jun 2024 15:34:42 +0800 Subject: [PATCH] chore: refactor tutorial according to anne PR --- docs/explanation/index.md | 1 - docs/how-to/index.md | 1 - docs/tutorial/getting-started.md | 81 +++++++++++++++++--------------- 3 files changed, 43 insertions(+), 40 deletions(-) diff --git a/docs/explanation/index.md b/docs/explanation/index.md index 3ee99fbc0..1b2e50fef 100644 --- a/docs/explanation/index.md +++ b/docs/explanation/index.md @@ -1,7 +1,6 @@ # Explanation ```{toctree} -:hidden: :titlesonly: :maxdepth: 1 diff --git a/docs/how-to/index.md b/docs/how-to/index.md index 80964714d..6362d67fa 100644 --- a/docs/how-to/index.md +++ b/docs/how-to/index.md @@ -1,7 +1,6 @@ # How-to guides ```{toctree} -:hidden: :titlesonly: :maxdepth: 1 diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md index b80e8b282..7878274d8 100644 --- a/docs/tutorial/getting-started.md +++ b/docs/tutorial/getting-started.md @@ -1,14 +1,15 @@ # Getting started -In this tutorial, we will download and install Pebble, configure layers, run the Pebble daemon, and work with layers and services. It takes about 15 minutes to complete. After this tutorial, you will have a basic understanding of what Pebble is, how to install it, and how to use it to orchestrate services. After that, you can continue exploring more advanced features and use cases (see links at the end). +In this tutorial, we will download and install Pebble, configure layers, run the Pebble daemon, and work with layers and services. After this tutorial, you will have a basic understanding of what Pebble is, how to install it, and how to use it to orchestrate services. It takes about 15 minutes to complete. + + +After that, you can continue exploring more advanced features and use cases (links at the end). ## Prerequisites - A Linux machine. -## Install Pebble - -### Download and install the latest release +## Download and install Pebble Find the latest tag on the [latest release page](https://github.com/canonical/pebble/releases/latest), then run the following commands to download, extract, and install the latest release (replace `v1.11.0` with the latest tag and `amd64` with your architecture): @@ -18,17 +19,15 @@ tar zxvf pebble_v1.11.0_linux_amd64.tar.gz sudo mv pebble /usr/local/bin/ # make sure it's in your $PATH ``` -### Install from source +## Verify Pebble installation -Alternatively, you can build and install Pebble from source: +Once the installation is complete, verify that `pebble` has been installed correctly by running: -1. Follow the official Go documentation [here](https://go.dev/doc/install) to download and install Go. -2. After installing, you will want to add the `$GOBIN` directory to your `$PATH` so you can use the installed tools. For more information, refer to the [official documentation](https://go.dev/doc/install/source#environment). -3. Run `go install github.com/canonical/pebble/cmd/pebble@latest` to build and install Pebble. - -### Check that it's working +```bash +pebble +``` -After installation, if you run `pebble`, you should see some output equivalent to the following: +This should produce output similar to the following: ```bash Pebble lets you control services and perform management actions on @@ -41,7 +40,9 @@ Usage: pebble [...] ## Configure Pebble -First, create a directory for Pebble configuration: +Now that Pebble has been installed, we can set up a basic configuration. + +First, let's create a directory for Pebble configuration: ```bash mkdir -p ~/PEBBLE/layers @@ -49,7 +50,7 @@ export PEBBLE=$HOME/PEBBLE echo "export PEBBLE=$HOME/PEBBLE" >> ~/.bashrc # add $PEBBLE to your bashrc ``` -Then, create a simple layer: +Next, create a layer by running: ```bash echo """\ @@ -69,15 +70,19 @@ services: This creates a simple layer containing only one service (which runs a basic HTTP server using Python's `http` module, listening on port 8080). -## Run the Pebble daemon +## Start the Pebble daemon + +Now we are ready to run the Pebble daemon. Pebble is invoked using `pebble `. (To get more information, run `pebble -h`.) +To start the daemon, run: + ```bash pebble run ``` -You should get some output similar to the following: +This starts the Pebble daemon itself, as well as all the services that are marked as `startup: enabled` (in our simple layer created above, the `http-server` service is marked as `startup: enabled`). You should get some output similar to the following: ```bash 2024-06-02T11:30:02.925Z [pebble] Started daemon. @@ -87,39 +92,39 @@ You should get some output similar to the following: ... ``` -This starts the Pebble daemon, and as you can see from the log, our HTTP server is already started, which can be verified by running `curl localhost:8080` in another terminal tab. +As you can see from the log, our HTTP server is started too, which can be verified by running `curl localhost:8080` in another terminal tab. -To exit the Pebble daemon, press Ctrl-C (which sends an "interrupt" signal to the process). +> Note: To exit the Pebble daemon, press Ctrl-C (which sends an "interrupt" signal to the process). -## View, start, and stop services +## View, start and stop services -You can view the status of services by running `pebble services`. Open another terminal tab, and run: +While the Pebble daemon is running, you can view the status of services by running `pebble services`. Open another terminal tab, and run: ```bash pebble services ``` -You should see output similar to: +You should see output similar to the following: ```bash Service Startup Current Since http-server enabled active today at 11:30 UTC ``` -Use `pebble stop ...` to stop one or more services. Run: +Use `pebble stop ...` to stop one or more services. You can stop the running `http-server` service by running: ```bash pebble stop http-server ``` -And the service `http-server` is stopped. We can verify it by viewing all the services: Run `pebble services`, and you can see it from the output: +You should get output similar to the following: ```bash Service Startup Current Since http-server enabled inactive today at 11:33 UTC ``` -And, if we run `curl localhost:8080`, we get a "connection refused" error, which confirms the service is down. +Now the service `http-server` is stopped. If we run `curl localhost:8080` again, we get a "connection refused" error, which confirms the service is down. To start it again, run: @@ -127,11 +132,9 @@ To start it again, run: pebble start http-server ``` -And it's started now. - ## Add a new layer -Now let's add another layer containing a different HTTP server. Create a new layer: +Now let's add another layer containing a different service that is also an HTTP server. To create a new layer, run: ```bash echo """\ @@ -146,28 +149,30 @@ services: summary: demo http server 2 command: python3 -m http.server 8081 startup: enabled -""" > $PEBBLE/layers/002-another-server.yaml +""" > $PEBBLE/layers/002-another-http-server.yaml ``` -This creates another layer containing only one service running an HTTP server listening on a different port 8081. Then let's add this layer to a plan: +This creates another layer that also contains a single service (running a basic +HTTP server using the Python `http.server` module listening on a different port 8081). + +Add the new layer to a Pebble plan by running: ```bash -pebble add layer1 $PEBBLE/layers/002-another-server.yaml +pebble add layer1 $PEBBLE/layers/002-another-http-server.yaml ``` -You will see output similar to the following: +If the layer is added successfully, the above command should produce the following output: ```bash -Layer "layer1" added successfully from "/home/ubuntu/PEBBLE_HOME/layers/002-another-server.yaml" +Layer "layer1" added successfully from "/home/ubuntu/PEBBLE_HOME/layers/002-another-http-server.yaml" ``` -When we update the service configuration by adding a layer, the services changed won't be automatically restarted. If we check the services: +Even though the service configuration has been updated with the newly added layer, the newly added services won't be automatically started. If we check the services: ```bash pebble services ``` - -We can see that although a new service has been added, it's not active yet: +We can see that although the new service `http-server-2` has been added, it's still "inactive": ```bash Service Startup Current Since @@ -187,13 +192,13 @@ And you get output similar to: 2024-06-02T11:40:39Z INFO Service "http-server" already started. ``` -Now if we check all the services: +Now if we check all the services again: ```bash pebble services ``` -We can see that the new HTTP server defined in the newly added layer has been started as well: +We can see that the new HTTP server `http-server-2` defined in the newly added layer should have been started and be shown as "active": ```bash Service Startup Current Since @@ -201,7 +206,7 @@ http-server enabled active today at 11:34 UTC http-server-2 enabled active today at 11:40 UTC ``` -## Where to go from here +## Next steps - To learn more about running the Pebble daemon, see [How to run the daemon (server)](../how-to/run-the-daemon.md). - To learn more about viewing, starting and stopping services, see [How to view, start, and stop services](../how-to/view-start-stop-services.md).