search

numberscope / backscope

Numberscope's back end: responsible for getting sequences and other data from the On-Line Encyclopedia of Integer Sequences, pre-processing it (factoring etc), and storing it.
MIT License
1 stars 9 forks source link

readme.md should correctly reflect needed setup steps #24

Open katestange opened 2 years ago

katestange commented 2 years ago

The setup documentation doesn't currently match what you actually need to do to get set up. This needs to be updated. I'm going to include below the extra steps I needed to do and the ways my experience didn't match.

(1) Issue #23 occurred

(2) Before doing step "2." in the "Initial Setup" section, you need to install postgres and set up a database and user. I did the following: Install postgres: sudo apt install postgresql postgresql-contrib Create a user: sudo -u postgres createuser --interactive and followed the prompts to name my user numberscope but not give superuser permission (I did allow to create databases, but perhaps that's not needed; I did not allow creation of roles). Then I made a database with sudo -u postgres createdb numberscope Then I set a password for user numberscope on database numberscope by first going into the postgres shell by sudo su - postgres and then into psql by psql numberscope postgres and then the command for the password is ALTER USER numberscope PASSWORD '<pass_you_choose>' then get out by doing \q exit Test the password with psql -h localhost -d numberscope numberscope The database name ("numberscope" is what I used above), user name (again "numberscope" is what I used above) and password should match the .env file in step "2."

(3) In step "3.", the command psql -d numberscope didn't work, but I think the purpose is served by psql -h localhost -d numberscope numberscope as in (2) above; I think we are just checking it's all there.

(4) At this point, I ran the backend with the first of the two options presented in the section "Running the Application" and then I did the test indicated by going to (http://127.0.0.1:5000/api/get_oeis_sequence/A00045/50). However, instead of displaying terms, it returned the message Error invalid OEIS ID: A00045. The URL had an error (too few 0's -- also there's something more wrong with how the directions are written in the documentation right now, although I was able to guess). Going to (http://127.0.0.1:5000/api/get_oeis_sequence/A000045/50) instead returned the terms desired, indicating (I hope) that the backend is working.

gwhitney commented 2 years ago

This is an excellently detailed issue and is not far from being its own PR... a couple of comments: (1) As @HristopoulosSt can testify, the postgres installation is going to be highly OS-specific. So we will want to break down that portion of the readme into Windows, Mac, and Linux sections (and sadly it will be different on different Linux distributions as well). So we might want to put a reference in the main readme to an additional document we supply on setting up postgres. (2) As I mentioned in a comment to #23, the postgres installation should precede the pip install step in the setup. I believe that will eliminate #23 in practice without any other changes.

By way of "explanation" of how things got as they are, I think the readme was written from the point of view of someone who had postgres already on their machine pre-dating working with Numberscope, so for whomever that was, a working Postgres with a reasonable user at hand and a working pg_config executable was just a presupposition. Since we will have folks trying to install this that have never heard of Postgres, we need to remove that presuppostion (but note that once we have the u of colorado server updated and running steadily and automatically incorporating code improvements, there will be many fewer installations of the backscope -- really the only reason to do it will be to work on the back end itself; most people who work with any of this code will install the frontscope and just use the standard backscope running at colorado).

katestange commented 2 years ago

A further comment that there should be a section in the documentation that specifies what you need to do on subsequent times you want to boot it up, after you've set it up (i.e. differentiate one-time setup steps from every-time boot steps).

gwhitney commented 2 years ago

A further comment that there should be a section in the documentation that specifies what you need to do on subsequent times you want to boot it up, after you've set it up (i.e. differentiate one-time setup steps from every-time boot steps).

Agreed. Are there any other every-time steps besides enter the virtual environment (venv) and execute python3 manage.py runserver? That's all I do.

katestange commented 2 years ago

Me too.

liammulh commented 2 years ago

Related to #41.

gwhitney commented 2 years ago

Is there anything else that needs to be done for this issue? Do we need to document how to update the database when schema changes are made? That probably needs to go somewhere, not sure if it is there.

liammulh commented 2 years ago

Do we need to document how to update the database when schema changes are made?

That's a good idea.

According to https://flask-migrate.readthedocs.io/en/latest/, "each time the database models change repeat the migrate and upgrade commands."

But... "Alembic is currently unable to detect table name changes, column name changes, or anonymously named constraints."

liammulh commented 1 year ago

I'm not working on this right now. Unassigning myself.