Add utilization section to the documentation

Signed-off-by: Akashdeep Dhar <[email protected]>
fedora-infra · Aug 14, 2024 · e857cb8 · e857cb8
1 parent d687299
commit e857cb8
Showing 1 changed file with 133 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -42,6 +42,139 @@
     (venv) $ poetry install
     ```
 
+### Utilization
+
+### For development
+
+1.  Make sure that the virtual environment that was recently created was activated.
+    ```
+    $ cd webhook-to-fedora-messaging
+    ```
+    ```
+    $ source venv/bin/activate
+    ```
+2.  Make a copy of the stored `logging.yaml.example` and change it to reflect your custom logging settings.
+    ```
+    (venv) $ cp logging.yaml.example logging.yaml
+    ```
+    ```
+    (venv) $ nano logging.yaml
+    ```
+3.  Make a copy of the stored `config.example` and change it to reflect your custom application settings.
+    ```
+    (venv) $ cp config.example config
+    ```
+    ```
+    (venv) $ nano config
+    ```
+4.  Start the application with the `--help` flag to understand how the application command line works.
+    ```
+    (venv) $ w2fm --help
+    ```
+    Example output
+    ```
+    Usage: w2fm [OPTIONS] COMMAND [ARGS]...
+    
+    Options:
+      -c, --conf PATH  Read configuration from the specified module
+      --version        Show the version and exit.
+      --help           Show this message and exit.
+    
+    Commands:
+      setup  Setup the database schema in the specified environment
+    ```
+5.  While pointing towards the edited config file, run the `setup` command to initialize the database.
+    ```
+    (venv) $ w2fm --conf config setup
+    ```
+    Example output
+    ```
+    The database has been created
+    ```
+6.  Note that the same command can be used to upgrade and downgrade through database schema revisions.
+7.  Once the database is created, run the following command to invoke the service application.
+    ```
+    $ (venv) uvicorn \
+               --factory "webhook_to_fedora_messaging.main:create_app" \
+               --log-config logging.yaml
+               --host 0.0.0.0 \
+               --port 8080 \
+               --workers 4
+    ```
+    Example output
+    ```
+    [W2FM] [2024-08-14 01:56:48 +0530] [INFO] Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)
+    [W2FM] [2024-08-14 01:56:48 +0530] [INFO] Started parent process [11076]
+    [W2FM] [2024-08-14 01:56:49 +0530] [INFO] Started server process [11081]
+    [W2FM] [2024-08-14 01:56:49 +0530] [INFO] Waiting for application startup.
+    [W2FM] [2024-08-14 01:56:49 +0530] [INFO] Started server process [11080]
+    [W2FM] [2024-08-14 01:56:49 +0530] [INFO] Waiting for application startup.
+    [W2FM] [2024-08-14 01:56:49 +0530] [INFO] Application startup complete.
+    [W2FM] [2024-08-14 01:56:49 +0530] [INFO] Application startup complete.
+    [W2FM] [2024-08-14 01:56:49 +0530] [INFO] Started server process [11079]
+    [W2FM] [2024-08-14 01:56:49 +0530] [INFO] Waiting for application startup.
+    [W2FM] [2024-08-14 01:56:49 +0530] [INFO] Application startup complete.
+    [W2FM] [2024-08-14 01:56:49 +0530] [INFO] Started server process [11078]
+    [W2FM] [2024-08-14 01:56:49 +0530] [INFO] Waiting for application startup.
+    [W2FM] [2024-08-14 01:56:49 +0530] [INFO] Application startup complete.
+    ```
+    This command will make `4 workers` processes of the service available on `all interfaces` and on `port 8080`, while logging according to the configuration available in the newly created `logging.yaml` file.
+8.  To stop the service application processes, invoke a keyboard interrupt by pressing `Ctrl` + `C`.
+    ```
+    Ctrl + C
+    ```
+    Example output
+    ```
+    ^C
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Shutting down
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Shutting down
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Shutting down
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Shutting down
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Waiting for application shutdown.
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Waiting for application shutdown.
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Waiting for application shutdown.
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Application shutdown complete.
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Application shutdown complete.
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Application shutdown complete.
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Finished server process [11079]
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Finished server process [11078]
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Finished server process [11081]
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Waiting for application shutdown.
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Application shutdown complete.
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Finished server process [11080]
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Received SIGINT, exiting.
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Terminated child process [11078]
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Terminated child process [11079]
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Terminated child process [11080]
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Terminated child process [11081]
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Waiting for child process [11078]
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Waiting for child process [11079]
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Waiting for child process [11080]
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Waiting for child process [11081]
+    [W2FM] [2024-08-14 01:58:43 +0530] [INFO] Stopping parent process [11076]
+    ```
+9.  For more utility options on running the service, start `uvicorn` with the `--help` flag.
+    ```
+    (venv) $ uvicorn --help
+    ```
+    Example output
+    ```
+    Usage: uvicorn [OPTIONS] APP
+
+    Options:
+      --host TEXT                     Bind socket to this host.  [default:
+                                      127.0.0.1]
+      --port INTEGER                  Bind socket to this port. If 0, an available
+                                      port will be picked.  [default: 8000]
+      --uds TEXT                      Bind to a UNIX domain socket.
+      --fd INTEGER                    Bind to socket from this file descriptor.
+    ...
+    ```
+10. Deactivate the virtual environment by running the following command.
+    ```
+    (venv) $ deactivate
+    ```
+
 ## From cookiecutter template
 
 This is where you describe Webhook to Fedora Messaging.