INSTALL.md improvements based on Paul Morris' notes

PaulMorris commented 7 years ago

Below are notes I took while installing the PSM based on INSTALL.md. I tried to make a note every time I was confused about something, if even just a little bit. So not all of these items need to lead to edits, but they're all here for completeness.

NOTES

The biggest issue was I read the 'requirements overview' section and started installing things at that point, before getting to 'installation instructions'. (Sumana has some ideas on how to avoid this problem.)

When installing wildfly 10, the wildfly website talks about 'full' and 'web' versions of wildfly. There ended up being no difference in what you install, but it was slightly confusing for a moment. So maybe mention this in some way, or maybe not worth it.

On Ubuntu 16.04 the postgresql-9.6 package is not found:

$ sudo apt install postgresql-9.6
Reading package lists... Done
Building dependency tree
Reading state information... Done
E: Unable to locate package postgresql-9.6
E: Couldn't find any package by glob 'postgresql-9.6'
E: Couldn't find any package by regex 'postgresql-9.6'

$ sudo apt-get install postgresql-9.6
[sudo] password for paul:
Reading package lists... Done
Building dependency tree
Reading state information... Done
E: Unable to locate package postgresql-9.6
E: Couldn't find any package by glob 'postgresql-9.6'
E: Couldn't find any package by regex 'postgresql-9.6'

even after $ sudo apt update...

It worked after adding the apt repository per https://www.postgresql.org/download/linux/ubuntu/

sudo apt-get install postgresql-9.6Reading package lists... Done
Building dependency tree
Reading state information... Done
The following additional packages will be installed:
  libpq5 postgresql-client-9.6 postgresql-contrib-9.6
Suggested packages:
  locales-all postgresql-doc-9.6 libdbd-pg-perl
The following NEW packages will be installed:
  postgresql-9.6 postgresql-client-9.6 postgresql-contrib-9.6
The following packages will be upgraded:
  libpq5
1 upgraded, 3 newly installed, 0 to remove and 39 not upgraded.
Need to get 6,031 kB of archives.
After this operation, 28.3 MB of additional disk space will be used.
Do you want to continue? [Y/n]
Get:1 http://apt.postgresql.org/pub/repos/apt xenial-pgdg/main amd64 libpq5 amd64 10.0-1.pgdg16.04+1 [156 kB]
Get:2 http://apt.postgresql.org/pub/repos/apt xenial-pgdg/main amd64 postgresql-client-9.6 amd64 9.6.5-1.pgdg16.04+2 [1,226 kB]
Get:3 http://apt.postgresql.org/pub/repos/apt xenial-pgdg/main amd64 postgresql-9.6 amd64 9.6.5-1.pgdg16.04+2 [4,155 kB]
Get:4 http://apt.postgresql.org/pub/repos/apt xenial-pgdg/main amd64 postgresql-contrib-9.6 amd64 9.6.5-1.pgdg16.04+2 [495 kB]
Fetched 6,031 kB in 1s (4,100 kB/s)
(Reading database ... 355519 files and directories currently installed.)
Preparing to unpack .../libpq5_10.0-1.pgdg16.04+1_amd64.deb ...
Unpacking libpq5:amd64 (10.0-1.pgdg16.04+1) over (9.5.9-0ubuntu0.16.04) ...
Selecting previously unselected package postgresql-client-9.6.
Preparing to unpack .../postgresql-client-9.6_9.6.5-1.pgdg16.04+2_amd64.deb ...
Unpacking postgresql-client-9.6 (9.6.5-1.pgdg16.04+2) ...
Selecting previously unselected package postgresql-9.6.
Preparing to unpack .../postgresql-9.6_9.6.5-1.pgdg16.04+2_amd64.deb ...
Unpacking postgresql-9.6 (9.6.5-1.pgdg16.04+2) ...
Selecting previously unselected package postgresql-contrib-9.6.
Preparing to unpack .../postgresql-contrib-9.6_9.6.5-1.pgdg16.04+2_amd64.deb ...
Unpacking postgresql-contrib-9.6 (9.6.5-1.pgdg16.04+2) ...
Processing triggers for libc-bin (2.23-0ubuntu9) ...
Processing triggers for postgresql-common (173) ...
Building PostgreSQL dictionaries from installed myspell/hunspell packages...
  en_us
Removing obsolete dictionary files:
Setting up libpq5:amd64 (10.0-1.pgdg16.04+1) ...
Setting up postgresql-client-9.6 (9.6.5-1.pgdg16.04+2) ...
update-alternatives: using /usr/share/postgresql/9.6/man/man1/psql.1.gz to provide /usr/share/man/man1/psql.1.gz (psql.1.gz) in auto mode
Setting up postgresql-9.6 (9.6.5-1.pgdg16.04+2) ...
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Unescaped left brace in regex is deprecated, passed through in regex; marked by <-- HERE in m/(?<!\\)\${ <-- HERE ([^}]+)}/ at /usr/sbin/pam_getenv line 78.
Creating new cluster 9.6/main ...
  config /etc/postgresql/9.6/main
  data   /var/lib/postgresql/9.6/main
  locale en_US.UTF-8
  socket /var/run/postgresql
  port   5432
update-alternatives: using /usr/share/postgresql/9.6/man/man1/postmaster.1.gz to provide /usr/share/man/man1/postmaster.1.gz (postmaster.1.gz) in auto mode
Setting up postgresql-contrib-9.6 (9.6.5-1.pgdg16.04+2) ...
Processing triggers for libc-bin (2.23-0ubuntu9) ...

"Stop the server if it is already running" How do I know if it is running? Should it be running? Maybe a little more disclaimer here in the wording that it shouldn't be running yet.

Warnings on starting wildfly just for the record. Nothing to do here, there's already a "warnings are ok" message in the doc.

13:16:05,215 WARN  [org.jboss.as.txn] (ServerService Thread Pool -- 60) WFLYTX0013: Node identifier property is set to the default value. Please make sure it is unique.

13:16:06,424 WARN  [org.jboss.as.domain.management.security] (MSC service thread 1-1) WFLYDM0111: Keystore /home/paul/ots/wildfly-10.1.0.Final/standalone/configuration/application.keystore not found, it will be auto generated on first use with a self signed certificate for host localhost

13:18:58,851 WARN  [org.jboss.as.domain.management.security] (default I/O-2) WFLYDM0113: Generated self signed certificate at /home/paul/ots/wildfly-10.1.0.Final/standalone/configuration/application.keystore. Please note that self signed certificates are not secure, and should only be used for testing purposes. Do not use this self signed certificate in production.
SHA-1 fingerprint of the generated key is b7:08:f4:30:fb:34:92:cb:3d:24:f1:e9:d6:00:d6:e5:4c:6e:77:bb
SHA-256 fingerprint of the generated key is 7d:00:3e:f2:05:34:d8:e0:5b:d1:be:a7:06:75:73:64:34:96:9f:ce:f7:c7:fc:24:6e:ca:27:85:3d:28:9b:75

Had to enter psm psm for user and password, but this was not mentioned in the docs. Might be worth being more explicit that this is needed and which user/psw. (Where exactly was this?)

This line was slightly different than what the docs mentioned: 13:28:04,474 INFO [org.jboss.as.server] (management-handler-thread - 6) WFLYSRV0010: Deployed "postgresql-42.1.4.jar" (runtime-name : "postgresql-42.1.4.jar")

In the docs is: 15:32:15, 773 INFO [org.jboss.as.server] )ServerService Thread Pool --37) WFLYSRV0010: Deployed "postgresql-42.1.1.jar" (runtime-name: "postgresql-42.1.1.jar")

Docs say: You will need a database user, and a database owned by that user. Create them, and make a note of the password for the database user:

$ sudo -u postgres createuser --pwprompt psm

I thought psm in the line above was the password (not the user name) and changed it to my password at first.

Maybe a note about 'in the wildfly directory' for those commands? Generally more clarity on what directory the commands are run from would be helpful.

'Fill in your local properties:' is vague, maybe reword for more explicitness.

"log in with your management console username and password" maybe add "if you are not already logged in"

"Deployments > Deploy an Application > start" Maybe more specific wording? tabs at top vs links in page, etc.

"Deployments > Add > Upload a new deployment > browse to file." Which file do I browse to to deploy? Could be clearer here.

Jason helped set me up with: .pgpass in home directory which allows no password entry every time for postgres Maybe add this to the docs?

Maybe more of a Table of Contents at top for better road-map / overview.

Under build docs, which directory for the gradlew command? (psm/psm-app)

on doc build, 3 warnings:

:cms-web:apiDocs /home/paul/ots/psm/psm-app/cms-web/src/main/java/gov/medicaid/controllers/EnrollmentPageFlowController.java:294: warning - @param argument "ticketId" is not a parameter name. /home/paul/ots/psm/psm-app/cms-web/src/main/java/gov/medicaid/controllers/EnrollmentPageFlowController.java:767: warning - @param argument "entity" is not a parameter name. /home/paul/ots/psm/psm-app/cms-web/src/main/java/gov/medicaid/controllers/EnrollmentPageFlowController.java:784: warning - @param argument "entity" is not a parameter name. 3 warnings

PaulMorris commented 7 years ago

A few further possibilities that aren't in the current PR #477:

Do we want to add instructions for adding a .pgpass file to skip password entry for postgres?
Maybe use different usernames/passwords for the db and wildfly user accounts, say psm and psmdb, to make it easy to differentiate the two.
Maybe document how to start over with a clean slate if things go wrong. (I think there's a script for this?)
Would it be worth showing how to test the db setup by logging into it directly from terminal?
The details in the Requirements section about 'JNDI name' settings seem too detailed, more about how to configure the requirements than just a brief overview of them. Would it be better to move them to Install section?

cecilia-donnelly commented 6 years ago

As discussed with @PaulMorris, I'm noting which items from his notes I think we should change in INSTALL.

Had to enter psm psm for user and password, but this was not mentioned in the docs. Might be worth being more explicit that this is needed and which user/psw. (Where exactly was this?)

Yes, please add this.

Maybe use different usernames/passwords for the db and wildfly user accounts, say psm and psmdb, to make it easy to differentiate the two.

Yes, I think that's a good idea.

Maybe document how to start over with a clean slate if things go wrong. (I think there's a script for this?)

Yes, that's a good idea. I think you're thinking of scripts/rebuild-and-change-schema-for-testing.sh.

Would it be worth showing how to test the db setup by logging into it directly from terminal?

I think this gets to "how familiar do we expect people to be with PostgreSQL?" I don't want to provide a psql tutorial in our INSTALL docs. It might be worth pointing to an existing one, though.

jvasile commented 6 years ago

Would it be worth showing how to test the db setup by logging into it directly from terminal?

A one-liner that logs into the db, dumps schema and tests for presence of a keyword might be doable as a test.

Actually, we have tests. Some of those tests presumably verify that the db is there, accessible, and has the schema. I wonder how hard it would be to run those on our db (as opposed to on a db created by a test fixture). It would be nice to be able to say "Yep, your db looks good" or "Your db is borked for X reason."

SolutionGuidance / psm

INSTALL.md improvements based on Paul Morris' notes #472