Skip to content

Commit b2523bb

Browse files
mhermher
committed
Update docs
1 parent 55558ba commit b2523bb

21 files changed

+438
-375
lines changed

‎README.rst‎

Lines changed: 23 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -12,19 +12,16 @@ Flower
1212
.. image:: https://img.shields.io/pypi/v/flower.svg
1313
:target: https://pypi.python.org/pypi/flower
1414

15-
Flower is a web based tool for monitoring and administrating Celery clusters.
15+
Flower is an open-source web application for monitoring and managing Celery clusters.
16+
It provides real-time information about the status of Celery workers and tasks.
1617

1718
Features
1819
--------
1920

2021
- Real-time monitoring using Celery Events
21-
22-
- Task progress and history
23-
- Ability to show task details (arguments, start time, runtime, and more)
24-
- Graphs and statistics
25-
22+
- View task progress and history
23+
- View task details (arguments, start time, runtime, and more)
2624
- Remote Control
27-
2825
- View worker status and statistics
2926
- Shutdown and restart worker instances
3027
- Control worker pool size and autoscale settings
@@ -33,17 +30,12 @@ Features
3330
- View scheduled tasks (ETA/countdown)
3431
- View reserved and revoked tasks
3532
- Apply time and rate limits
36-
- Configuration viewer
3733
- Revoke or terminate tasks
38-
3934
- Broker monitoring
40-
4135
- View statistics for all Celery queues
42-
- Queue length graphs
43-
44-
- HTTP API
45-
- Basic Auth, Google, Github, Gitlab and Okta OAuth
36+
- HTTP Basic Auth, Google, Github, Gitlab and Okta OAuth
4637
- Prometheus integration
38+
- API
4739

4840
Installation
4941
------------
@@ -52,61 +44,35 @@ Installing `flower` with `pip <http://www.pip-installer.org/>`_ is simple ::
5244

5345
$ pip install flower
5446

55-
Development version can be installed with ::
47+
The development version can be installed from Github ::
5648

5749
$ pip install https://github.com/mher/flower/zipball/master#egg=flower
5850

5951
Usage
6052
-----
6153

62-
**Important** Please note that from version 1.0.1 Flower uses Celery 5 and has to be invoked in the same style as celery
63-
commands do.
64-
65-
The key takeaway here is that the Celery app's arguments have to be specified after the `celery` command and Flower's
66-
arguments have to be specified after the `flower` sub-command.
67-
68-
This is the template to follow::
69-
70-
celery [celery args] flower [flower args]
54+
To run Flower, you need to provide the broker URL ::
7155

72-
Core Celery args that you may want to set::
56+
$ celery --broker=amqp://guest:guest@localhost:5672// flower
7357

74-
-A, --app
75-
-b, --broker
76-
--result-backend
58+
Or use the configuration of `celery application <https://docs.celeryq.dev/en/stable/userguide/application.html>`_ ::
7759

78-
More info on available `Celery command args <https://docs.celeryq.dev/en/stable/reference/cli.html#celery>`_.
60+
$ celery -A tasks.app flower
7961

80-
For Flower command args `see here <https://flower.readthedocs.io/en/latest/config.html#options>`_.
62+
By default, flower runs on port 5555, which can be modified with the :ref:`port` option ::
8163

82-
Usage Examples
83-
--------------
64+
$ celery -A tasks.app flower --port=5001
8465

85-
Launch the Flower server at specified port other than default 5555 (open the UI at http://localhost:5566): ::
66+
You can also run Flower using the docker image ::
8667

87-
$ celery flower --port=5566
68+
$ docker run -v examples:/data -p 5555:5555 mher/flower celery --app=tasks.app flower
8869

89-
Specify Celery application path with address and port for Flower: ::
90-
91-
$ celery -A proj flower --address=127.0.0.6 --port=5566
92-
93-
Launch using docker: ::
94-
95-
$ docker run -p 5555:5555 mher/flower
96-
97-
Launch with unix socket file: ::
98-
99-
$ celery flower --unix-socket=/tmp/flower.sock
100-
101-
Broker URL and other configuration options can be passed through the standard Celery options (notice that they are after
102-
Celery command and before Flower sub-command): ::
103-
104-
$ celery -A proj --broker=amqp://guest:guest@localhost:5672// flower
70+
In this example, Flower is using the `tasks.app` defined in the `examples/tasks.py <https://github.com/mher/flower/blob/master/examples/tasks.py>`_ file
10571

10672
API
10773
---
10874

109-
Flower API enables to manage the cluster via REST API.
75+
Flower API enables to manage the cluster via HTTP `REST API.
11076

11177
For example you can restart worker's pool by: ::
11278

@@ -120,21 +86,21 @@ Or terminate executing task by: ::
12086

12187
$ curl -X POST -d 'terminate=True' http://localhost:5555/api/task/revoke/8a4da87b-e12b-4547-b89a-e92e4d1f8efd
12288

123-
For more info checkout `API Reference`_ and `examples`_.
89+
For more info checkout `API Reference`_
12490

12591
.. _API Reference: https://flower.readthedocs.io/en/latest/api.html
126-
.. _examples: http://nbviewer.ipython.org/urls/raw.github.com/mher/flower/master/docs/api.ipynb
12792

12893
Documentation
12994
-------------
13095

131-
Documentation is available at `Read the Docs`_ and `IPython Notebook Viewer`_
96+
Documentation is available at `Read the Docs`_
13297

13398
.. _Read the Docs: https://flower.readthedocs.io
134-
.. _IPython Notebook Viewer: http://nbviewer.ipython.org/urls/raw.github.com/mher/flower/master/docs/api.ipynb
13599

136100
License
137101
-------
138102

139-
Flower is licensed under BSD 3-Clause License. See the LICENSE file
140-
in the top distribution directory for the full license text.
103+
Flower is licensed under BSD 3-Clause License.
104+
See the `License`_ file for the full license text.
105+
106+
.. _`License`: https://github.com/mher/flower/blob/master/LICENSE

‎docs/api.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
API Reference
22
=============
33

4-
.. toctree::
5-
:maxdepth: 2
4+
For security reasons, the Flower API is disabled by default when authentication is not enabled.
5+
To enable the API for unauthenticated environments, you can set the FLOWER_UNAUTHENTICATED_API
6+
environment variable to true.
67

78
.. autotornado:: flower.app:Flower()
8-

‎docs/auth.rst‎

Lines changed: 81 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,136 +1,135 @@
11
.. _authentication:
2+
23
Authentication
34
==============
45

5-
Protecting your Flower instance from unwarranted access is important
6-
if it runs in an untrusted environment. Below, we outline the various
7-
forms of authentication supported by Flower.
6+
Flower supports a variety of authentication methods, including Basic Authentication, Google, GitHub,
7+
GitLab, and Okta OAuth. You can also customize and use your own authentication method.
88

9-
**NOTE:** The following endpoints are exempt from authentication:
9+
The following endpoints are exempt from authentication:
1010

1111
- /healthcheck
1212
- /metrics
1313

14-
.. _basic-auth:
14+
.. _basic-authentication:
1515

1616
HTTP Basic Authentication
1717
-------------------------
1818

19-
Securing Flower with Basic Authentication is easy.
19+
Flower supports Basic Authentication as a built-in authentication method, allowing you to secure access to the
20+
Flower using simple username and password credentials. This authentication method is commonly used for
21+
straightforward authentication requirements.
22+
23+
To enable basic authentication, use :ref:`basic_auth` option. This option allows you to specify a list of
24+
username and password pairs for authentication.
2025

21-
The `--basic_auth` option accepts `user:password` pairs separated by
22-
a comma. If configured, any client trying to access this
23-
Flower instance will be prompted to provide the credentials specified in
24-
this argument: ::
26+
For example, running Flower with the following :ref:`basic_auth` option will protect the Flower UI and
27+
only allow access to users providing the username user and the password pswd::
2528

26-
$ celery flower --basic_auth=user1:password1,user2:password2
29+
$ celery flower --basic-auth=user:pswd
2730

2831
See also :ref:`reverse-proxy`
2932

3033
.. _google-oauth:
3134

32-
Google OAuth 2.0
33-
----------------
35+
Google OAuth
36+
------------
37+
38+
Flower provides authentication support using Google OAuth, enabling you to authenticate users through their Google accounts.
39+
This integration simplifies the authentication process and offers a seamless experience for users who are already logged into Google.
3440

35-
Flower supports Google OAuth 2.0. This way you can authenticate any user
36-
with a Google account. Google OAuth 2.0 authentication is enabled using the
37-
`--auth`, `--oauth2_key`, `--oauth2_secret` and `--oauth2_redirect_uri` options.
41+
Follow the steps below to configure and use Google OAuth authentication:
3842

39-
`--auth` is a regular expression, for granting access only to the specified email pattern.
40-
`--oauth2_key` and `--oauth2_secret` are your credentials from your `Google Developer Console`_.
41-
`--oauth2_redirect_uri` is there to specify what is the redirect_uri associated to your key and secret
43+
1. Go to the `Google Developer Console`_
44+
2. Select a project, or create a new one.
45+
3. In the sidebar on the left, select Credentials.
46+
4. Click CREATE CREDENTIALS and click OAuth client ID.
47+
5. Under Application type, select Web application.
48+
6. Name OAuth 2.0 client and click Create.
49+
7. Copy the "Client secret" and "Client ID"
50+
8. Add redirect URI to the list of Authorized redirect URIs
4251

43-
For instance, if you want to grant access to `[email protected]` and `[email protected]`: ::
52+
Here's an example configuration file with the Google OAuth options:
4453

45-
$ celery flower --auth="[email protected]|[email protected]" --oauth2_key=... --oauth2_secret=... --oauth2_redirect_uri=http://flower.example.com/login
54+
.. code-block:: python
4655
47-
Alternatively, you can set environment variables instead of command line arguments: ::
56+
auth_provider="flower.views.auth.GoogleAuth2LoginHandler"
57+
auth="allowed-emails.*@gmail.com"
58+
oauth2_key="<your_client_id>"
59+
oauth2_secret="<your_client_secret>"
60+
oauth2_redirect_uri="http://localhost:5555/login"
4861
49-
$ export FLOWER_OAUTH2_KEY=...
50-
$ export FLOWER_OAUTH2_SECRET=...
51-
$ export FLOWER_OAUTH2_REDIRECT_URI=http://flower.example.com/login
52-
$ celery flower --auth=.*@example\.com
62+
Replace `<your_client_id>` and `<your_client_secret>` with the actual Client ID and secret obtained from
63+
the Google Developer Console.
5364

5465
.. _Google Developer Console: https://console.developers.google.com
5566

5667
.. _github-oauth:
5768

58-
Okta OAuth
69+
GitHub OAuth
5970
------------
6071

61-
Flower also supports Okta OAuth. Flower should be registered in
62-
<https://developer.okta.com/docs/guides/add-an-external-idp/openidconnect/register-app-in-okta/>
63-
before getting started. See `Okta OAuth API`_ docs for more info.
72+
Flower also supports GitHub OAuth. Before getting started, Flower should be registered in
73+
`Github Settings`_.
6474

65-
Okta OAuth should be activated using `--auth_provider` option.
66-
The client id, secret and redirect uri should be provided using
67-
`--oauth2_key`, `--oauth2_secret`, `--oauth2_redirect_uri` options or using
68-
`FLOWER_OAUTH2_KEY`, `FLOWER_OAUTH2_SECRET`, `FLOWER_OAUTH2_REDIRECT_URI` environment variables.
75+
Github OAuth is activated by setting :ref:`auth_provider` to `flower.views.auth.GithubLoginHandler`.
76+
Here's an example configuration file with the Github OAuth options:
6977

70-
The URL from which OAuth2 API URLs will be built should be set using `FLOWER_OAUTH2_OKTA_BASE_URL`
71-
environment variable: ::
78+
.. code-block:: python
7279
73-
$ export FLOWER_OAUTH2_KEY=7956724aafbf5e1a93ac
74-
$ export FLOWER_OAUTH2_SECRET=f9155f764b7e466c445931a6e3cc7a42c4ce47be
75-
$ export FLOWER_OAUTH2_REDIRECT_URI=http://localhost:5555/login
76-
$ export FLOWER_OAUTH2_OKTA_BASE_URL=https://my-company.okta.com/oauth2
77-
$ celery flower --auth_provider=flower.views.auth.OktaLoginHandler --auth=.*@example\.com
80+
auth_provider="flower.views.auth.GithubLoginHandler"
81+
auth="allowed-emails.*@gmail.com"
82+
oauth2_key="<your_client_id>"
83+
oauth2_secret="<your_client_secret>"
84+
oauth2_redirect_uri="http://localhost:5555/login"
7885
79-
.. _Okta OAuth API: https://developer.okta.com/docs/reference/api/oidc/
86+
Replace `<your_client_id>` and `<your_client_secret>` with the actual Client ID and secret obtained from
87+
the Github Settings.
8088

81-
GitHub OAuth
82-
------------
83-
84-
Flower also supports GitHub OAuth. Flower should be registered in
85-
<https://github.com/settings/applications/new> before getting started.
8689
See `GitHub OAuth API`_ docs for more info.
8790

88-
GitHub OAuth should be activated using `--auth_provider` option.
89-
The client id, secret and redirect uri should be provided using
90-
`--oauth2_key`, `--oauth2_secret` and `--oauth2_redirect_uri` options or using
91-
`FLOWER_OAUTH2_KEY`, `FLOWER_OAUTH2_SECRET` and `FLOWER_OAUTH2_REDIRECT_URI`
92-
environment variables. ::
91+
.. _Github Settings: https://github.com/settings/applications/new
92+
.. _GitHub OAuth API: https://developer.github.com/v3/oauth/
9393

94-
$ export FLOWER_OAUTH2_KEY=7956724aafbf5e1a93ac
95-
$ export FLOWER_OAUTH2_SECRET=f9155f764b7e466c445931a6e3cc7a42c4ce47be
96-
$ export FLOWER_OAUTH2_REDIRECT_URI=http://localhost:5555/login
97-
$ celery flower --auth_provider=flower.views.auth.GithubLoginHandler --auth=.*@example\.com
94+
.. _okta-oauth:
9895

99-
.. _GitHub OAuth API: https://developer.github.com/v3/oauth/
96+
Okta OAuth
97+
----------
10098

101-
.. _gitlab-oauth:
99+
Flower also supports Okta OAuth. Before getting started, you need to register Flower in `Okta`_.
100+
Okta OAuth is activated by setting :ref:`auth_provider` option to `flower.views.auth.OktaLoginHandler`.
101+
102+
Okta OAuth requires `oauth2_key`, `oauth2_secret` and `oauth2_redirect_uri` options which should be obtained from Okta.
103+
Okta OAuth also uses `FLOWER_OAUTH2_OKTA_BASE_URL` environment variable.
104+
105+
See Okta `Okta OAuth API`_ docs for more info.
102106

103-
**NOTE:** If you need a custom GitHub Domain, please export it using environment variable:
104-
`export FLOWER_GITHUB_OAUTH_DOMAIN=github.foobar.com`
107+
.. _Okta: https://developer.okta.com/docs/guides/add-an-external-idp/openidconnect/main/
108+
.. _Okta OAuth API: https://developer.okta.com/docs/reference/api/oidc/
109+
110+
.. _gitlab-oauth:
105111

106112
GitLab OAuth
107113
------------
108114

109-
Flower also supports GitLab OAuth. Flower should be registered in
110-
<https://gitlab.com/profile/applications> before getting started.
111-
See `GitLab OAuth2 API`_ docs for more info.
115+
Flower also supports GitLab OAuth for authentication. To enable GitLab OAuth, follow the steps below:
112116

113-
GitLab OAuth should be activated using `--auth_provider` option.
114-
The client id, secret and redirect uri should be provided using
115-
`--oauth2_key`, `--oauth2_secret` and `--oauth2_redirect_uri` options or using
116-
`FLOWER_OAUTH2_KEY`, `FLOWER_OAUTH2_SECRET` and `FLOWER_OAUTH2_REDIRECT_URI`
117-
environment variables.
117+
1. Register Flower as an application at GitLab. You can refer to the `GitLab OAuth documentation`_ for detailed instructions on how to do this.
118+
2. Once registered, you will obtain the credentials for Flower configuration.
119+
3. In your Flower configuration, set the following options to activate GitLab OAuth:
120+
- :ref:`auth_provider` to `flower.views.auth.GitlabLoginHandler`.
121+
- :ref:`oauth2_key` to the "Application ID" obtained from GitLab.
122+
- :ref:`oauth2_secret` to the "Secret" obtained from GitLab.
123+
- :ref:`oauth2_redirect_uri`: Set this to the redirect URI configured in GitLab.
124+
4. (Optional) To restrict access to specific GitLab groups, you can utilize the `FLOWER_GITLAB_AUTH_ALLOWED_GROUPS` environment variable. Set it to a comma-separated list of allowed groups. You can include subgroups by using the `/` character. For example: `group1,group2/subgroup`.
125+
5. (Optional) The default minimum required group access level can be adjusted using the `FLOWER_GITLAB_MIN_ACCESS_LEVEL` environment variable.
126+
6. (Optional) The custom GitHub Domain can be adjusted using the `FLOWER_GITLAB_OAUTH_DOMAIN` environment variable.
118127

119-
A list of allowed GitLab groups can be specified using the
120-
`FLOWER_GITLAB_AUTH_ALLOWED_GROUPS` environment variable (e.g. ``group1,group2/subgroup``).
128+
For further details on GitLab OAuth and its implementation, refer to the `Group and project members API`_ documentation.
129+
It provides comprehensive information and guidelines on working with GitLab's OAuth functionality.
121130

122-
The default minimum required group access level can be changes by
123-
`FLOWER_GITLAB_MIN_ACCESS_LEVEL` environment variable.
124-
See `Group and project members API`_ for details.
125-
126-
$ export FLOWER_OAUTH2_KEY=7956724aafbf5e1a93ac
127-
$ export FLOWER_OAUTH2_SECRET=f9155f764b7e466c445931a6e3cc7a42c4ce47be
128-
$ export FLOWER_OAUTH2_REDIRECT_URI=http://localhost:5555/login
129-
$ export FLOWER_GITLAB_AUTH_ALLOWED_GROUPS=group1,group2/subgroup
130-
$ celery flower --auth_provider=flower.views.auth.GitLabLoginHandler --auth=.*@example\.com
131+
See also `GitLab OAuth2 API`_ documentation for more info.
131132

133+
.. _GitLab OAuth documentation: https://docs.gitlab.com/ee/integration/oauth_provider.htm
132134
.. _GitLab OAuth2 API: https://docs.gitlab.com/ee/api/oauth2.html
133135
.. _Group and project members API: https://docs.gitlab.com/ee/api/members.html
134-
135-
**NOTE:** If you need a custom GitHub Domain, please export it using environment variable:
136-
`export FLOWER_GITLAB_OAUTH_DOMAIN=gitlab.foobar.com`

0 commit comments

Comments
 (0)