Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update info in Dataverse Developers Guide about what happens when not specifying a branch when running script that deploys Dataverse on AWS #10589

Merged
merged 2 commits into from
Jun 3, 2024

Conversation

jggautier
Copy link
Contributor

@jggautier jggautier commented May 23, 2024

Correct info about what happens when -b is not used in command to create a Dataverse instance on AWS

What this PR does / why we need it:
Addresses the problem described in #10572 by editing the section of the Dataverse Developer guide about spinning up Dataverse instances on AWS.

Which issue(s) this PR closes:
Closes #10572

Suggestions on how to test this:
Review the revised section of the Dataverse Developer guide about spinning up Dataverse instances on AWS. It should let the user know that when she runs the script to spin up a Dataverse instance without the -b option, the latest version of Dataverse is used.

Does this PR introduce a user interface change? If mockups are available, please link/include them here:
No, this PR doesn't introduce a user interface change.

Is there a release notes update needed for this change?:
I don't think a release note is needed for this change.

Correct info about what happens when -b is not used in command to create a Dataverse instance on AWS
Copy link
Member

@pdurbin pdurbin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jggautier @donsizemore I added some thoughts.

@@ -96,7 +96,7 @@ To run it with default values you just need the script, but you may also want a
ec2-create-instance accepts a number of command-line switches, including:

* -r: GitHub Repository URL (defaults to https://github.com/IQSS/dataverse.git)
* -b: branch to build (defaults to develop)
* -b: branch to build (defaults to the latest release of Dataverse)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* -b: branch to build (defaults to the latest release of Dataverse)
* -b: branch to build and deploy (e.g. "develop") rather than deploying the latest release of Dataverse

I think, I hope, the above is a little more clear, and it gives an example of which branch can be passed.

What's a bit confusing is that the script itself spits out "develop" three times, even when called with no arguments. It probably should say "deploying latest release of Dataverse". Here's what it says now:

$ ./ec2-create-instance.sh 
using default repo: https://github.com/IQSS/dataverse.git
using default branch develop
using ami-0408f4c4a072e3fb9
using t3a.large
using dataverse-sg security group
Creating EC2 instance
Instance ID: aaa
When you are done, please terminate your instance with:
aws  ec2 terminate-instances --instance-ids aaa
giving instance 90 seconds to wake up...
End creating EC2 instance
New instance created with ID "aaa". To ssh into it:
ssh -i  [email protected]
Please wait at least 15 minutes while the branch "develop" from https://github.com/IQSS/dataverse.git is being deployed.
Branch develop from https://github.com/IQSS/dataverse.git has been deployed to http://foo.bar
To ssh into the new instance:
ssh -i  [email protected]
When you are done, please terminate your instance with:
aws  ec2 terminate-instances --instance-ids aaa

This script is in the ansible repo so we'd need to fix it there.

@jggautier
Copy link
Contributor Author

jggautier commented May 23, 2024

Ah okay, this is sounding like more than a Dataverse Guide documentation change then, right? What the script spits out might need to change, like you wrote, and the documentation at https://github.com/GlobalDataverseCommunityConsortium/dataverse-ansible/tree/develop/ec2 also says that the default branch is develop and that may need to change.

Unless you or @donsizemore or @landreev think something else should be done, by the end of tomorrow I'll delete this PR and re-write the issue at #10572 so it's also about correcting what the script itself spits out and correcting what's mentioned in the documentation in the dataverse-ansible repo.

@pdurbin
Copy link
Member

pdurbin commented May 23, 2024

@jggautier I mean, we could use this PR to simply delete some of the confusing stuff. What if we do something like this?

$ git diff source/developers/deployment.rst
diff --git a/doc/sphinx-guides/source/developers/deployment.rst b/doc/sphinx-guides/source/developers/deployment.rst
index 678e29f407..89ae9ac4c2 100755
--- a/doc/sphinx-guides/source/developers/deployment.rst
+++ b/doc/sphinx-guides/source/developers/deployment.rst
@@ -91,17 +91,11 @@ Download `ec2-create-instance.sh`_ and put it somewhere reasonable. For the purp
 
 .. _ec2-create-instance.sh: https://raw.githubusercontent.com/GlobalDataverseCommunityConsortium/dataverse-ansible/master/ec2/ec2-create-instance.sh
 
-To run it with default values you just need the script, but you may also want a current copy of the ansible `group vars <https://raw.githubusercontent.com/GlobalDataverseCommunityConsortium/dataverse-ansible/master/defaults/main.yml>`_ file.
+To run the script, you can make it executable (``chmod 755 ec2-create-instance.sh``) or run it with bash, like this with ``-h`` as an argument to print the help:
 
-ec2-create-instance accepts a number of command-line switches, including:
+``bash ~/Downloads/ec2-create-instance.sh -h``
 
-* -r: GitHub Repository URL (defaults to https://github.com/IQSS/dataverse.git)
-* -b: branch to build (defaults to develop)
-* -p: pemfile directory (defaults to $HOME)
-* -g: Ansible GroupVars file (if you wish to override role defaults)
-* -h: help (displays usage for each available option)
-
-``bash ~/Downloads/ec2-create-instance.sh -b develop -r https://github.com/scholarsportal/dataverse.git -g main.yml``
+If you run the script without any arguments, it should spin up the latest version of Dataverse.
 
 You will need to wait for 15 minutes or so until the deployment is finished, longer if you've enabled sample data and/or the API test suite. Eventually, the output should tell you how to access the Dataverse installation in a web browser or via SSH. It will also provide instructions on how to delete the instance when you are finished with it. Please be aware that AWS charges per minute for a running instance. You may also delete your instance from https://console.aws.amazon.com/console/home?region=us-east-1 .

@jggautier
Copy link
Contributor Author

Ah I see. So you're proposing removing the entire list of options and telling the user to use -h to see the list, right?

When someone uses -h to see all of the options, do they see everything that's in the list that's being removed? Will what's returned when using -h need to be edited, too?

@pdurbin
Copy link
Member

pdurbin commented May 24, 2024

Yes, everything and more. Note especially the "Usage" line, which I'll repeat for easy reading:

Usage: ./ec2-create-instance.sh -b <branch> -r <repo> -p <pem_path> -g <group_vars> -a <dataverse-ansible branch> -i aws_image -u aws_user -s aws_size -t aws_tag -f aws_security group -e aws_profile -l local_log_path -d -v

$ ./ec2-create-instance.sh -h
Usage: ./ec2-create-instance.sh -b <branch> -r <repo> -p <pem_path> -g <group_vars> -a <dataverse-ansible branch> -i aws_image -u aws_user -s aws_size -t aws_tag -f aws_security group -e aws_profile -l local_log_path -d -v
default branch is develop
default repo is https://github.com/IQSS/dataverse
default .pem location is /Users/pdurbin
example group_vars may be retrieved from https://raw.githubusercontent.com/GlobalDataverseCommunityConsortium/dataverse-ansible/develop/defaults/main.yml
default AWS AMI ID is ami-0408f4c4a072e3fb9, find the full list at https://rockylinux.org/ami/
default AWS user is rocky
default AWS instance size is t3a.large
default AWS security group is dataverse-sg
local log path will rsync Payara, Jacoco, Maven and other logs back to the specified path
-d will destroy (terminate) the AWS instance once testing and reporting completes
-v increases Ansible output verbosity

@jggautier
Copy link
Contributor Author

jggautier commented May 24, 2024

Thanks. So I think I should change the issue so that we're recommending:

  1. Editing the section of the Dataverse Guide the way you described in your earlier comment. I could edit the .rst file in this PR.
  2. Editing the documentation in the dataverse-ansible repo in the same way.
  3. Updating what's returned when someone runs ./ec2-create-instance.sh -h

And since this isn't a documentation-only issue it doesn't get fast tracked the way other "small" documentation-only issues would.

For the second and third recommendations, would that involve creating PRs in the dataverse-ansible repo?

@pdurbin
Copy link
Member

pdurbin commented May 24, 2024

Well, I think we can fast track # 1.

Yes, 2 and 3 would happen in the ansible repo.

Removing list of options and encouraging users to user -h to see the options.
@jggautier jggautier changed the title Update info in Developer Guide about default branch used by script that deploys Dataverse on AWS Update info about what happens when not specifying a branch when running script that deploys Dataverse on AWS May 24, 2024
@jggautier jggautier changed the title Update info about what happens when not specifying a branch when running script that deploys Dataverse on AWS Update info in Dataverse Developers Guide about what happens when not specifying a branch when running script that deploys Dataverse on AWS May 24, 2024
@jggautier
Copy link
Contributor Author

I updated the .rst file in this PR the way you described in #10589 (comment) and opened an issue in the ansible repo about updating the documentation there and updating what's returned when someone runs ./ec2-create-instance.sh -h

@jggautier
Copy link
Contributor Author

There's some discussion today in the GitHub issue at gdcc/dataverse-ansible#355. It seems like there's some doubt that needs to be resolved about whether or not the develop branch is used when ec2-create-instance.sh is run without using the -b option.

Copy link
Member

@pdurbin pdurbin left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me. Approved.

@pdurbin
Copy link
Member

pdurbin commented May 28, 2024

Oh, I just saw the doubts. I'm trying it.

@pdurbin
Copy link
Member

pdurbin commented May 28, 2024

I tried running the create script with no arguments but it failed with this:

TASK [dataverse : install R modules] *******************************************
changed: [localhost] => (item=R2HTML)
changed: [localhost] => (item=rjson)
failed: [localhost] (item=DescTools)

Here's the full output: install-fail-2d7f797.txt

So I still don't know for sure if you get "develop" or the latest release.

@jggautier we could remove this line from the PR, if you want:

If you run the script without any arguments, it should spin up the latest version of Dataverse.

@pdurbin
Copy link
Member

pdurbin commented May 28, 2024

failed: [localhost] (item=DescTools)

I opened an issue:

@jggautier
Copy link
Contributor Author

jggautier commented May 29, 2024

@jggautier we could remove this line from the PR, if you want:

If you run the script without any arguments, it should spin up the latest version of Dataverse.

I'm not sure. You're suggesting this because we could make this documentation change sooner than anyone can fix whatever is preventing us from creating an instance to check whether or not the develop branch is used when we run ec2-create-instance.sh with no -b argument, right?

I suppose that makes sense as long as we also remove this info from the docs in the dataverse-ansible repo and from the output when we run ec2-create-instance.sh -h.

Then after we're able to run ec2-create-instance.sh without arguments and see if the develop branch is used, I could create new issues for updating the docs and ec2-create-instance.sh -h output with info about what happens when -b is used.

@pdurbin
Copy link
Member

pdurbin commented Jun 3, 2024

As discussed in standup, I'm going to go ahead and merge this. Here's a preview from https://dataverse-guide--10589.org.readthedocs.build/en/10589/developers/deployment.html#download-and-run-the-create-instance-script

Screenshot 2024-06-03 at 11 16 12 AM

We've established that if you run the create script with no arguments, you get the latest release.

A follow up would be to update the script itself, which we are tracking here:

@pdurbin pdurbin merged commit ed1f169 into develop Jun 3, 2024
2 of 3 checks passed
@pdurbin pdurbin added this to the 6.3 milestone Jun 3, 2024
@pdurbin pdurbin deleted the 10572-aws-default-branch branch June 3, 2024 15:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
2 participants