Re: [PR] docs: simplify the Quickstart guide [superset]
mistercrunch merged PR #27612: URL: https://github.com/apache/superset/pull/27612 -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
mistercrunch commented on code in PR #27612: URL: https://github.com/apache/superset/pull/27612#discussion_r1542182673 ## docs/docs/quickstart.mdx: ## @@ -4,61 +4,42 @@ hide_title: false sidebar_position: 2 --- -**Ready to give Apache Superset a try?** This quickstart will help you run Superset on your local machine in -**5 simple steps**. It assumes that you have [Docker](https://www.docker.com) installed. +**Ready to give Apache Superset a try?** This quickstart guide will help you +get up and running on your local machine in **3 simple steps**. Note that +it assumes that you have [Docker](https://www.docker.com), +[docker-compose](https://docs.docker.com/compose/), and +[git](https://git-scm.com/) installed. + +:::caution +While we recommend using `docker-compose` for a quick start in a sandbox-type +environment and for other development-type use cases, **we +do not recommend this setup for production**. For this purpose please +refer to our +[Installing on Kubernetes](/docs/installation/running-on-kubernetes/) +page. +::: ### 1. Get Superset -To get started, set the `SUPERSET_VERSION` environment variable with the latest Superset version. -[Click here](https://github.com/apache/superset/releases) to check the latest version. -``` -$ export SUPERSET_VERSION= +```bash +$ git clone https://github.com/apache/superset ``` -Pull the Superset image from Docker Hub: +### 2. Start the latest official release of Superset ``` -$ docker pull apache/superset:$SUPERSET_VERSION -``` +# Enter the repository you just cloned +$ cd superset -### 2. Start Superset -:::tip -Note that some configuration is mandatory for Superset in order to start. In particular, Superset will not start without -a user-specified value of `SECRET_KEY` in a Superset configuration file or `SUPERSET_SECRET_KEY` as an environment variable. -Please see [Configuring Superset](/docs/installation/configuring-superset/) for more details. -::: +# Fire up Superset using docker-compose +$ docker-compose -f docker-compose-image-tag.yml up ``` -$ docker run -d -p 8080:8088 \ - -e "SUPERSET_SECRET_KEY=$(openssl rand -base64 42)" \ - -e "TALISMAN_ENABLED=False" \ - --name superset apache/superset:$SUPERSET_VERSION -``` - -### 3. Create an account -``` -$ docker exec -it superset superset fab create-admin \ - --username admin \ - --firstname Admin \ - --lastname Admin \ - --email admin@localhost \ - --password admin -``` - -### 4. Configure Superset -``` -$ docker exec -it superset superset db upgrade && - docker exec -it superset superset load_examples && - docker exec -it superset superset init -``` -:::tip -This step can take some time. While you wait, feel free to join the official Slack channel to check for new releases, -ask questions, and engage with the community. -[Click here to join.](http://bit.ly/join-superset-slack) -::: +This may take a moment as docker-compose will fetch the underlying +docker images and will load up some examples. Once all containers +are downloaded and the output settles, you're ready to log in. -### 5. Start using Superset -After configuring your fresh instance, head over to [http://localhost:8080](http://localhost:8080) and -log in with the default created account: +### 3. Log into Superset +Now head over to [http://localhost:8080](http://localhost:8080) and log in with the default created account: Review Comment: good catch! -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
artofcomputing commented on code in PR #27612: URL: https://github.com/apache/superset/pull/27612#discussion_r1540460793 ## docs/docs/quickstart.mdx: ## @@ -4,61 +4,42 @@ hide_title: false sidebar_position: 2 --- -**Ready to give Apache Superset a try?** This quickstart will help you run Superset on your local machine in -**5 simple steps**. It assumes that you have [Docker](https://www.docker.com) installed. +**Ready to give Apache Superset a try?** This quickstart guide will help you +get up and running on your local machine in **3 simple steps**. Note that +it assumes that you have [Docker](https://www.docker.com), +[docker-compose](https://docs.docker.com/compose/), and +[git](https://git-scm.com/) installed. + +:::caution +While we recommend using `docker-compose` for a quick start in a sandbox-type +environment and for other development-type use cases, **we +do not recommend this setup for production**. For this purpose please +refer to our +[Installing on Kubernetes](/docs/installation/running-on-kubernetes/) +page. +::: ### 1. Get Superset -To get started, set the `SUPERSET_VERSION` environment variable with the latest Superset version. -[Click here](https://github.com/apache/superset/releases) to check the latest version. -``` -$ export SUPERSET_VERSION= +```bash +$ git clone https://github.com/apache/superset ``` -Pull the Superset image from Docker Hub: +### 2. Start the latest official release of Superset ``` -$ docker pull apache/superset:$SUPERSET_VERSION -``` +# Enter the repository you just cloned +$ cd superset -### 2. Start Superset -:::tip -Note that some configuration is mandatory for Superset in order to start. In particular, Superset will not start without -a user-specified value of `SECRET_KEY` in a Superset configuration file or `SUPERSET_SECRET_KEY` as an environment variable. -Please see [Configuring Superset](/docs/installation/configuring-superset/) for more details. -::: +# Fire up Superset using docker-compose +$ docker-compose -f docker-compose-image-tag.yml up ``` -$ docker run -d -p 8080:8088 \ - -e "SUPERSET_SECRET_KEY=$(openssl rand -base64 42)" \ - -e "TALISMAN_ENABLED=False" \ - --name superset apache/superset:$SUPERSET_VERSION -``` - -### 3. Create an account -``` -$ docker exec -it superset superset fab create-admin \ - --username admin \ - --firstname Admin \ - --lastname Admin \ - --email admin@localhost \ - --password admin -``` - -### 4. Configure Superset -``` -$ docker exec -it superset superset db upgrade && - docker exec -it superset superset load_examples && - docker exec -it superset superset init -``` -:::tip -This step can take some time. While you wait, feel free to join the official Slack channel to check for new releases, -ask questions, and engage with the community. -[Click here to join.](http://bit.ly/join-superset-slack) -::: +This may take a moment as docker-compose will fetch the underlying +docker images and will load up some examples. Once all containers +are downloaded and the output settles, you're ready to log in. -### 5. Start using Superset -After configuring your fresh instance, head over to [http://localhost:8080](http://localhost:8080) and -log in with the default created account: +### 3. Log into Superset +Now head over to [http://localhost:8080](http://localhost:8080) and log in with the default created account: Review Comment: Superset doesn't start at port 8080, instead it starts at 8088 while using the docker-compose-image-tag.yml file. https://github.com/apache/superset/blob/349e496da519f3462aa5cff2d1bd76490b04fe5d/docker-compose-image-tag.yml#L52 -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
artofcomputing commented on code in PR #27612: URL: https://github.com/apache/superset/pull/27612#discussion_r1538072706 ## docs/docs/quickstart.mdx: ## @@ -4,61 +4,38 @@ hide_title: false sidebar_position: 2 --- -**Ready to give Apache Superset a try?** This quickstart will help you run Superset on your local machine in -**5 simple steps**. It assumes that you have [Docker](https://www.docker.com) installed. +**Ready to give Apache Superset a try?** This quickstart guide will help you +get up and running on your local machine in **3 simple steps**. Note that +it assumes that you have [Docker](https://www.docker.com), +[docker-compose](https://docs.docker.com/compose/), and +[git](https://git-scm.com/) installed. -### 1. Get Superset -To get started, set the `SUPERSET_VERSION` environment variable with the latest Superset version. -[Click here](https://github.com/apache/superset/releases) to check the latest version. - -``` -$ export SUPERSET_VERSION= -``` - -Pull the Superset image from Docker Hub: +:::caution +While we recommend using `docker-compose` for a quick start in a sandbox-type +environment and for other development-type use cases, **we +do not recommend this setup for production**. For this purpose please +refer to our +[Installing on Kubernetes](/docs/installation/running-on-kubernetes/) +page. +::: -``` -$ docker pull apache/superset:$SUPERSET_VERSION -``` +### 1. Get Superset -### 2. Start Superset -:::tip -Note that some configuration is mandatory for Superset in order to start. In particular, Superset will not start without -a user-specified value of `SECRET_KEY` in a Superset configuration file or `SUPERSET_SECRET_KEY` as an environment variable. -Please see [Configuring Superset](/docs/installation/configuring-superset/) for more details. -::: -``` -$ docker run -d -p 8080:8088 \ - -e "SUPERSET_SECRET_KEY=$(openssl rand -base64 42)" \ - -e "TALISMAN_ENABLED=False" \ - --name superset apache/superset:$SUPERSET_VERSION +```bash +$ git clone g...@github.com:apache/superset.git ``` -### 3. Create an account -``` -$ docker exec -it superset superset fab create-admin \ - --username admin \ - --firstname Admin \ - --lastname Admin \ - --email admin@localhost \ - --password admin -``` +### 2. Start the latest official release of Superset -### 4. Configure Superset ``` -$ docker exec -it superset superset db upgrade && - docker exec -it superset superset load_examples && - docker exec -it superset superset init +$ docker-compose -f docker-compose-image-tag.yml up Review Comment: This command won't work unless the user is already in Superset directory, should be `docker-compose -f superset/docker-compose-image-tag.yml up` or `cd superset && docker-compose -f docker-compose-image-tag.yml up` -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
artofcomputing commented on code in PR #27612: URL: https://github.com/apache/superset/pull/27612#discussion_r1538070518 ## docs/docs/quickstart.mdx: ## @@ -4,61 +4,38 @@ hide_title: false sidebar_position: 2 --- -**Ready to give Apache Superset a try?** This quickstart will help you run Superset on your local machine in -**5 simple steps**. It assumes that you have [Docker](https://www.docker.com) installed. +**Ready to give Apache Superset a try?** This quickstart guide will help you +get up and running on your local machine in **3 simple steps**. Note that +it assumes that you have [Docker](https://www.docker.com), +[docker-compose](https://docs.docker.com/compose/), and +[git](https://git-scm.com/) installed. -### 1. Get Superset -To get started, set the `SUPERSET_VERSION` environment variable with the latest Superset version. -[Click here](https://github.com/apache/superset/releases) to check the latest version. - -``` -$ export SUPERSET_VERSION= -``` - -Pull the Superset image from Docker Hub: +:::caution +While we recommend using `docker-compose` for a quick start in a sandbox-type +environment and for other development-type use cases, **we +do not recommend this setup for production**. For this purpose please +refer to our +[Installing on Kubernetes](/docs/installation/running-on-kubernetes/) +page. +::: -``` -$ docker pull apache/superset:$SUPERSET_VERSION -``` +### 1. Get Superset -### 2. Start Superset -:::tip -Note that some configuration is mandatory for Superset in order to start. In particular, Superset will not start without -a user-specified value of `SECRET_KEY` in a Superset configuration file or `SUPERSET_SECRET_KEY` as an environment variable. -Please see [Configuring Superset](/docs/installation/configuring-superset/) for more details. -::: -``` -$ docker run -d -p 8080:8088 \ - -e "SUPERSET_SECRET_KEY=$(openssl rand -base64 42)" \ - -e "TALISMAN_ENABLED=False" \ - --name superset apache/superset:$SUPERSET_VERSION +```bash +$ git clone g...@github.com:apache/superset.git Review Comment: This can be troublesome for users which have not configured git, maybe it can be `git clone https://github.com/apache/superset` ? -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
artofcomputing commented on PR #27612: URL: https://github.com/apache/superset/pull/27612#issuecomment-2018658118 > Can we agree that this approach is better than the previous single-docker/sqlite/5-steps approach? I'm planning on > improving the rest of the docs to clarify installation, but let's start here. > > One big assumption here is that "quick start" is about sandboxing (as in standing up something quickly that someone can play with, in a non-production environment). This fits the scope and direction I'm advocating for our usage of docker-compose... IMHO your direction and view is much more tangible and easier to grasp now, which I fully agree. It's also possible to use this direction to rewrite other pages by having the quick start as an example/baseline to simplify instructions. > About the question that's beyond the scope of this PR of "what we support"... I agree, there's no silver bullet. However, I think that the direction you're advocating for the quick start can be a good starting ground to provide better instructions on how to change between different solutions, -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
mistercrunch commented on PR #27612: URL: https://github.com/apache/superset/pull/27612#issuecomment-2018379397 > which are the official and supported installation methods This is beyond the scope of this PR. This PR is about improving quick start. Can we agree that this approach is better than the previous single-docker/sqlite/5-steps approach? I'm planning on improving the rest of the docs to clarify installation, but let's start here. -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
artofcomputing commented on PR #27612: URL: https://github.com/apache/superset/pull/27612#issuecomment-2016670015 >Oh for quickstart what I'm suggesting is in this PR (docker-compose pointing to the latest official release) >For installation there's a whole section, starting now with k8s, but getting on all sorts of nooks and crannies... -> > https://superset.apache.org/docs/installation/running-on-kubernetes > ... > For development setups -> https://github.com/apache/superset/blob/master/CONTRIBUTING.md That wasn't the question, which are the official and supported installation methods and where in the documentation they are declared? Yes, there's multiple installation pages, however Docker Compose is now declared as a method not suitable for production deployment on top of the page, would that be suitable for having a Quickstart with it? And what about PyPI? If so, there needs to be a page where users can be informed which are the methods the Superset community supports. Again, without it, "truly supported" means nothing. >What's clear is that this documentation evolved bits by bits through different generations of contributors. This quickstart >re-write is a first take towards re-thinking / merging / sorting through all this. That's true, IMHO Superset has advanced quite a lot throughout the years, however the documentation hasn't so far been able to keep up with the development pace, making it the least favorable selling point of Superset. There's a lot of work to be done. >I think it's becoming clear to me that for quickstart/sandbox/development docker-compose is the preferred way and for >production Helm/k8s is the way, supported by minikube for smaller, single-host-type setups. I agree, the documentation can be definitely geared towards these methods, but they must be agreed upon by the community, and also stated on the documentation so as not to generate any confusion to the users. That was also another oversight when the Quickstart was written (which is fixed in this PR). -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
mistercrunch commented on PR #27612: URL: https://github.com/apache/superset/pull/27612#issuecomment-2016185403 Oh for quickstart what I'm suggesting is in this PR (docker-compose pointing to the latest official release) For installation there's a whole section, starting now with k8s, but getting on all sorts of nooks and crannies... -> https://superset.apache.org/docs/installation/running-on-kubernetes https://github.com/apache/superset/assets/487433/a4624bba-e81b-43ba-9d47-ac73e46c2761;> For development setups -> https://github.com/apache/superset/blob/master/CONTRIBUTING.md What's clear is that this documentation evolved bits by bits through different generations of contributors. This quickstart re-write is a first take towards re-thinking / merging / sorting through all this. I think it's becoming clear to me that for quickstart/sandbox/development docker-compose is the preferred way and for production Helm/k8s is the way, supported by minikube for smaller, single-host-type setups. -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
artofcomputing commented on PR #27612: URL: https://github.com/apache/superset/pull/27612#issuecomment-2016110416 > Whenever we offer more options it dilutes what is truly supported and creates confusion I can't find in the documentation what is the official installation methods, would you mind telling me where it is? If not, "truly supported" means nothing if the user can't find it. > We could factor out this method as yet another way to run Superset into the "installation and configuration" under "shaky single host docker setup with SQL lite" Again, simply declare the official supported installation methods and we can go from there. Only Kubernetes is supported? Let's do a Quickstart with Kubernetes. Both Kubernetes and Compose? Let's offer both. > Oh one more thing about the current quickstart is that AFAIK it cannot be configured easily, meaning it's a configurability dead end. I agree, that was a big oversight when it was written, since Superset configuration is catered towards a declarative method. Yet, there's no mention about Superset being declarative at the start, it should be actually documented in the intro. -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
mistercrunch commented on PR #27612: URL: https://github.com/apache/superset/pull/27612#issuecomment-2015435539 Oh one more thing about the current quickstart is that AFAIK it cannot be configured easily, meaning it's a configurability dead end. If someone wanted to install a database driver to connect to their database or simply flipping a feature flag, they'd probably have to go inside the docker and mess around with things. On the docker-compose side of the house things are evolutive and well documented around configurability. There are clear prescribed ways to do these things. -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
mistercrunch commented on PR #27612: URL: https://github.com/apache/superset/pull/27612#issuecomment-2015321571 Whenever we offer more options it dilutes what is truly supported and creates confusion. "Just tell me what I should use" is the way I'd feel entering a new community. There's shouldn't be many options for a quick start. We could factor out this method as yet another way to run Superset into the "installation and configuration" under "shaky single host docker setup with SQL lite" -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
artofcomputing commented on PR #27612: URL: https://github.com/apache/superset/pull/27612#issuecomment-2014880734 I agree in the sense of simplification, which was one of the main reasons that the Quickstart was created, as users weren't able to get a instance of Superset up and running easily beforehand. It's possible to have both installation methods in place, and let the user choose which one fits best their needs while informing the tradeoff of each. > It also looks like the current setup is also sqlite(?) and isn't persisted (?) Having a Postgres and some persistence in the image should be a positive upgrade here too. That's right, currently the standalone instance uses sqlite, yet the data is persisted by stopping the container instead of removing it, as the documentation informs. -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
mistercrunch commented on PR #27612: URL: https://github.com/apache/superset/pull/27612#issuecomment-2013946852 My take is I think we need to simplify things, use and expose higher level constructs. If people want to go lower level they can refer to the underlying scripts where all the information resides. Also related is I would love to strip "external" information that is not Superset-specific and is better maintained elsewhere. You need to install docker on a Mac? on Ubuntu? Look at the docker docs! -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
Re: [PR] docs: simplify the Quickstart guide [superset]
rusackas commented on PR #27612: URL: https://github.com/apache/superset/pull/27612#issuecomment-2013934933 @artofcomputing @michael-s-molina @eschutho @sfirke for more opinions. I wonder if there's a place for both methods. -- 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: notifications-unsubscr...@superset.apache.org For queries about this service, please contact Infrastructure at: us...@infra.apache.org - To unsubscribe, e-mail: notifications-unsubscr...@superset.apache.org For additional commands, e-mail: notifications-h...@superset.apache.org
