docs: restructure install flow, promote Docker as default #3483
Conversation
MoralCode
left a comment
MoralCode
left a comment
There was a problem hiding this comment.
We definitely need to do a restructuring like this, so thanks for the contribution!
Just wanted to correct some things about the language/phrasing used for certain things.
| .. note:: | ||
|
|
||
| We currently officially support the local installation of Augur from source on macOS, Ubuntu, and Fedora (but most UNIX-like systems will probably work with a few tweaks). We recommend either using the Docker images or setting up a virtual machine with a supported operating system installed if you are using Windows. | ||
| **Docker (Recommended for Quickstart)**: The fastest way to get Augur up and running with minimal setup. Ideal for trying out Augur, demonstrations, or light installations (~< 2,000 repos). |
There was a problem hiding this comment.
our instance (40k repos) uses docker, so IMO its viable for any size install.
| **Docker (Recommended for Quickstart)**: The fastest way to get Augur up and running with minimal setup. Ideal for trying out Augur, demonstrations, or light installations (~< 2,000 repos). | ||
|
|
||
| To install from source, we'll need to do a few things: | ||
| **Manual Installation (Recommended for Long-term Use)**: For production deployments, long-term data collection, or development work. We officially support macOS, Ubuntu, and Fedora. |
There was a problem hiding this comment.
IMO both are suitable for long term use, they're just different styles of managing software. I like docker because it gives us (the maintainers) so much control over the environment augur runs in and is more predictable for debugging issues.
| .. note:: | ||
|
|
||
| The next section will start with a database setup, and then you can continue with the following steps given below. | ||
| We recommend either using the Docker images or setting up a virtual machine with a supported operating system installed if you are using Windows. |
There was a problem hiding this comment.
docker installs on windows will basically already run in a virtual machine behind the scenes because containers rely on features of the linux kernel
|
|
||
| **Manual Installation** - For production deployments, development work, or if Docker isn't available on your platform. | ||
|
|
||
| Note: Augur's dependencies support Python 3.8 - Python 3.10. Python 3.11+ is not yet fully supported. |
There was a problem hiding this comment.
this is no longer true. 3.10/3.11 are currently the ones with the best support.
that said we shouldnt use language here that requires constant updates. I would just say that we support all officially supported versions of python (although some features may not work on brand new python versions as soon as they release)
There was a problem hiding this comment.
them i suggest removing the note part would be a way to solve this
|
Overall this PR contains a lot of changes that I think make it somewhat difficult to review. Maybe its best to do this in stages (i.e. submit a simple PR that just moves the "docker" section of the docs so that it is a subsection within "getting started" (ideally above the manual/advanced instal method). Then a followup Pr can make content changes to smooth out the differences and de-prioritize the manual install |
MoralCode
added
pending changes
|
i have looked on you feedback and will work on your suggestion .Would look forward to more such suggestions |
2 participants
Title:
docs: restructure install flow, promote Docker as default
Changes Made:
toc.rst: Reordered installation methods, placing Docker first; transformed separate Docker section into “Advanced Docker Deployment.”
quick-start.rst: Promoted Docker as the primary recommendation; added a side‑by‑side comparison matrix of Docker vs. manual install.
index.rst: Adjusted navigation to consolidate Docker under the Getting Started flow.
README.md: Updated entry point guidance to highlight Docker as the recommended default path
Summary:
This PR reorganizes the installation documentation to make Docker the default/primary installation method, while keeping manual installation paths available for advanced users. It addresses Issue #3477.