[GitHub] [airflow] potiuk commented on a change in pull request #18282: Refactor installation pages

[GitBox <gi...@apache.org>]

potiuk commented on a change in pull request #18282:
URL: https://github.com/apache/airflow/pull/18282#discussion_r710137403



##########
File path: docs/apache-airflow/installation/index.rst
##########
@@ -0,0 +1,335 @@
+ .. Licensed to the Apache Software Foundation (ASF) under one
+    or more contributor license agreements.  See the NOTICE file
+    distributed with this work for additional information
+    regarding copyright ownership.  The ASF licenses this file
+    to you under the Apache License, Version 2.0 (the
+    "License"); you may not use this file except in compliance
+    with the License.  You may obtain a copy of the License at
+
+ ..   http://www.apache.org/licenses/LICENSE-2.0
+
+ .. Unless required by applicable law or agreed to in writing,
+    software distributed under the License is distributed on an
+    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+    KIND, either express or implied.  See the License for the
+    specific language governing permissions and limitations
+    under the License.
+
+
+Installation
+------------
+
+.. contents:: :local:
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Installation
+    :hidden:
+
+    Prerequisites <prerequisites>
+    Dependencies <dependencies>
+    Supported versions <supported-versions>
+    Installing from sources <installing-from-sources>
+    Installing from PyPI <installing-from-pypi>
+    Setting up the database <setting-up-the-database>
+    Upgrading to Airflow 2 <upgrading-to-2>
+    Upgrade Check <upgrade-check>
+
+This page describes installations options that you might use when considering how to install Airflow.
+Airflow consists of many components, often distributed among many physical or virtual machines, therefore
+installation of Airflow might be quite complex, depending on the options you choose.
+
+You should also check-out the :doc:`Prerequisites <prerequisites>` that must be fulfilled when installing Airflow
+as well as  :doc:`Supported versions <supported-versions>` to know what are the policies for supporting
+Airflow, Python and Kubernetes.
+
+Airflow requires additional :doc:`Dependencies <dependencies>` to be installed - which can be done
+via extras and providers.
+
+When you install Airflow, you need to :doc:`setup the database <setting-up-the-database>` which must be
+kept updated when airflow is upgraded.
+
+If you came here to upgrade Airflow from 1.10 version (which is end-of-life already), follow the
+:doc:`Upgrading to Airflow 2 <upgrading-to-2>`.
+
+Using released sources
+''''''''''''''''''''''
+
+More details: :doc:`installing-from-sources`
+
+**When this option works best**
+
+This option is best if you expect to build all your software from sources.
+Apache Airflow is one of the projects that belong to the `Apache Software Foundation <https://www.apache.org/>`__ .
+It is a requirement for all ASF projects that they can be installed using official sources released via `Official Apache Mirrors <http://ws.apache.org/mirrors.cgi/>`__ .
+You can easily `Verify the integrity and provenance of the software <https://www.apache.org/dyn/closer.cgi#verify>`__
+
+**Intended users**
+
+Users who are familiar with installing and building software from sources and are conscious about integrity and provenance
+of the software they use down to the lowest level possible.
+
+**What are you expected to handle**
+
+You are expected to build and install airflow and its components on your own.
+You should develop and handle the deployment for all components of Airflow.
+
+You are responsible for setting up database, creating and managing database schema with ``airflow db`` commands,
+automated startup and recovery, maintenance, cleanup and upgrades of Airflow and the Airflow Providers.
+
+**What Apache Airflow Community provides for that method**
+
+You have `instructions <https://github.com/apache/airflow/blob/main/INSTALL>`__ on how to build the software but due to various environments
+and tools you might want to use, you might expect that there will be problems which are specific to your deployment and environment
+you will have to diagnose and solve.
+
+**Where to ask for help**
+
+The ``#development`` slack channel for building the software.
+
+The ``#troubleshooting`` slack is a channel for quick general troubleshooting questions. The
+`GitHub discussions <https://github.com/apache/airflow/discussions>`__ if you look for longer discussion and have more information to share.
+
+If you can provide description of a reproducible problem with Airflow software, you can open issue at `GitHub issues <https://github.com/apache/airflow/issues>`_
+
+Using PyPI
+'''''''''''
+
+More details:  :doc:`/installation/installing-from-pypi`
+
+**When this option works best**
+
+This installation method is useful when you are not familiar with Containers and Docker and want to install
+Apache Airflow on physical or virtual machines and you are used to installing and running software using custom
+deployment mechanism.
+
+The only officially supported mechanism of installation is via ``pip`` using constraint mechanisms. The constraint
+files are managed by Apache Airflow release managers to make sure that you can repeatably install Airflow from PyPI with all Providers and
+required dependencies.
+
+You can also verify integrity and provenance of the packages of the packages downloaded from PyPI as described at the installation
+page, but software you download from PyPI is pre-built for you so that you can install it without building.
+
+**Intended users**
+
+Users who are familiar with installing and configuring Python applications, managing Python
+environments, dependencies and running software with their custom deployment mechanisms.
+
+**What are you expected to handle**
+
+You are expected to install Airflow - all components of it - on your own.
+You should develop and handle the deployment for all components of Airflow.
+
+You are responsible for setting up database, creating and managing database schema with ``airflow db`` commands,
+automated startup and recovery, maintenance, cleanup and upgrades of Airflow and Airflow Providers.
+
+**What Apache Airflow Community provides for that method**
+
+You have `instructions <https://airflow.apache.org/docs/apache-airflow/stable/installation.html>`__
+on how to install the software but due to various environments and tools you might want to use, you might expect that there will be
+problems which are specific to your deployment and environment you will have to diagnose and solve.
+
+**Where to ask for help**
+
+The ``#troubleshooting`` channel on Airflow Slack for quick general
+troubleshooting questions. The `GitHub discussions <https://github.com/apache/airflow/discussions>`__
+if you look for longer discussion and have more information to share.
+
+If you can provide description of a reproducible problem with Airflow software, you can open
+issue at `GitHub issues <https://github.com/apache/airflow/issues>`__
+
+
+Using Production Docker Images
+''''''''''''''''''''''''''''''
+
+More details: :doc:`docker-stack:index`
+
+**When this option works best**
+
+This installation method is useful when you are familiar with Container/Docker stack. It provides a capability of
+running Airflow components in isolation from other software running on the same physical or virtual machines with easy
+maintenance of dependencies.
+
+The images are build by Apache Airflow release managers and they use officially released packages from PyPI and official constraint files
+- same that are used for installing airflow from PyPI.
+
+**Intended users**
+
+Users who are familiar with Containers and Docker stack and understand how to build their own container images.
+
+Users who understand how to install providers and dependencies from PyPI with constraints if they want to extend or customize the image.
+
+Users who now how to create deployments using Docker by linking together multiple docker containers and maintaining such deployments.

Review comment:
       I deliberately wanted to avoid an `assesment` which method is better or worse. I think first of all we can be biased becaue we have certain experience, and secondly - more importantly, this page is for very different people with diverse backgrounds, experience, expectations. 
   
   Something that might be "easiest" for me might be not "easiest" for someone who does not know anything about docker, containers and Kubernetes. It's not for us to judge,  the whole idea of that page is to give the users an objective comparison of what is expected from them if they choose certain path, what experience is needed, and what help and resources they will get. Then, those different users, based on their own backgrounds, habits. expectations, experience, use cases, might make their own choice. 
   
   I think it would very biased to tell that one option is "better" than "other" if we do not know who is reading that document
   




-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@airflow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org