search

pypi / warehouse

The Python Package Index
https://pypi.org
Apache License 2.0
3.58k stars 964 forks source link

Improve `make purge` documentation #3476

Open nlhkabu opened 6 years ago

nlhkabu commented 6 years ago

Today I had some trouble after an upgrade of postgres. I tried to run make purge to nuke everything, but it didn't do the job.

The solution was to run docker-compose down -v then re-run make serve and make initdb.

It would be good to:

  1. Make make purge leave the docker setup in a pristine state
  2. Document make purge at https://warehouse.readthedocs.io/development/getting-started/#troubleshooting

Current docs:

If sqlalchemy.exec.OperationalError is displayed in localhost after make serve has been executed, shut down / reset the Docker containers. When the containers have shut down, run make serve in one terminal window while running make initdb in a separate terminal window.

Maybe we could replace this with:

If sqlalchemy.exec.OperationalError is displayed in localhost after make serve has been executed, shut down / reset the Docker containers with make purge. After the containers have shut down, run make serve in one terminal window while running make initdb in a separate terminal window.

Thanks to @ewdurbin for helping me get everything up and running again :)

brainwane commented 6 years ago

I've also run into stuff like this and would appreciate a docs update.

di commented 6 years ago

3499 makes it so that a make purge will stop all running containers (same as make stop), and then purge them, so now it should perform as @nlhkabu expected.

I agree we should document make purge somewhere, something like:

To remove all containers related to Warehouse, you can run make purge from the repository root.

Thinking about it now, I'm not sure the bit about a sqlalchemy.exec.OperationalError is the best possible advice -- usually this will happen either because a) the developer missed a step and didn't make initdb, or b) there has been a migration since they last made their database, and they need to docker-compose run web python -m warehouse db upgrade head. Actually doing a purge/shutdown should rarely be necessary (although the Postgres update is one example).

I think the "empty DB" error is different enough that we can differentiate our advice better, but someone will have to experiment a bit to find out.