Skip to content

Update

Jump to bottom
Joe Wicentowski edited this page Nov 14, 2023 · 40 revisions

Update your history.state.gov Development Environment

These directions assume you have a fully configured history.state.gov Development Environment and that you need to update your system so that it contains the latest operating system, software dependencies, core applications, and configurations.

Install system updates

  1. From the Apple menu  in the top-left corner of your screen, choose System Settings. Click General in the sidebar, then click Software Update on the right. Or in earlier versions of macOS, choose Apple menu  > System Preferences, then click Software Update.

  2. Open the App Store (using the Spotlight (🔍) icon in the menu bar, search for App Store; or in Finder, select Go > Applications, and find App Store in the list of applications), select the Updates tab, and install all available updates.

Update the Apple Developer Command Line Tools

  1. After installing all system updates, you will need to install the current version of the Apple Developer Command Line Tools. To do so, open Terminal (using Spotlight, search for Terminal; or in Finder, select Go > Utilities), and paste in the following command:

     xcode-select --install

  2. If this command returns a message that says, error: command line tools already installed, then you can skip to the next step. Otherwise, you will see a dialog window with 3 buttons. Select Install, and let the installation complete. Or, it might tell you that you already have these tools installed, in which case you should proceed.

Update Homebrew

  1. We need to update Homebrew. To do so, enter the following command:

     brew update && brew upgrade

    This may take several minutes if it's been a long time since you've performed this action.

Update HSG software dependencies

  1. With Homebrew updated, we will use it to make sure you have all of the HSG software dependencies installed. Run the following commands to install any missing dependencies:

     brew uninstall liberica-jdk8-full node node@10

 brew untap bell-sw/liberica

 brew tap homebrew/cask-versions
 
 brew install temurin8

    If prompted, enter the password for your the user account on your Mac. If any of the applications are already installed, Homebrew will skip them, retaining the existing installation.

  2. Make sure that the following icons are in your Dock: eXist-db, oXygen XML Editor, GitHub Desktop, and OpenVPN Connect. If any are not there, go to Finder, and select Go > Applications, and drag the respective applications' icons into the dock. (It's likely that the icons of updated apps will disappear from your Dock as a result of the command above, due to a known issue with Homebrew.)

  3. Run brew doctor to check your Homebrew installation, and follow any instructions to resolve problems that it reports. Keep running brew doctor until it reports:

    Your system is ready to brew.

    Sometimes the problems reported by brew doctor are inscrutable. Contact Joe if you are unable to decipher these.

  4. In preparation for installing nvm, a utility for installing and managing versions of Node.JS, we want to ensure your Mac is using the "Z shell" (Zsh) and not the "Bash" shell as its default login shell. First, ensure the .zshrc file exists:

     touch ~/.zshrc

  5. Check which default login shell your Mac is using:

     echo $0

    If the response is -zsh, then skip ahead to the next step ("Install nvm...").

    If the answer is -bash, then enter this command to change your shell from the "Bash" shell to the "Z shell" (Zsh):

     chsh -s /bin/zsh

    Close the current Terminal window, and open a new window via Terminal's Shell menu > New Window > New Window.... Opening a new Terminal window is necessary to ensure that the next step runs in the Z shell environment instead.

  6. Install nvm, our required version of Node.JS, and two Node.JS-based dependencies:

     curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash

 source ~/.zshrc

 nvm install 14.19.3

 npm install -g gulp bower

Set up eXist

Note for users of Apple Silicon (M1, M2)-based Macs: Use the following Terminal command to start eXist:

    /Applications/eXist-db.app/Contents/Resources/bin/startup.sh

To quit eXist, type Control-C into the Terminal window.

  1. Start eXist by clicking on its app icon in your Dock.

  2. A dialog window will open asking if you want to open eXist. Select Open. (If this dialog doesn't appear, please proceed.)

  3. A dialog window will open showing eXist's configuration properties. Select Save. When prompted to create the data directory or confirm the location of the data directory, select Yes. (If this dialog doesn't appear, please proceed.)

  4. The eXist splash screen will appear as eXist performs its startup routine. Once the eXist splash screen disappears, a new, blueish, X-shaped icon will appear in your menu bar. This is the eXist menu bar icon. Click this icon and select Quit to quit eXist.

Set up oXygen

  1. Start oXygen XML Editor by clicking on its app icon in your Dock.

  2. A dialog window will open asking if you want to open oXygen. Select Open.

  3. From the External Tools toolbar menu (i.e., the green, triangle-shaped icon), select these, one by one, waiting for each to complete (i.e. show BUILD SUCCESSFUL) before proceeding:

    • Pull updates from all repositories
    • 1. Apply Mac settings to hsg-project
    • 2. Clone all repositories & resources
    • 3. Apply hsg-project settings to eXist

  4. If you use eXist to preview website content, then start eXist via its app icon in your Dock. During startup eXist will show a splash screen.

  5. To prepare your local eXist database with all of the files needed to run a local copy of HSG, go to the Tools dropdown menu in oXygen and select 4. Deploy all repositories to localhost. This step takes about 10-15 minutes on our computers. On a remote computer, this step could take as long as 40 minutes, depending on your computer's hardware.

  6. Now a complete copy of history.state.gov is now running at http://localhost:8080/exist/apps/hsg-shell/.

Prepare for publishing

If you publish to history.state.gov, be sure you have completed the relevant steps in the Setup article for:

  • OpenVPN
  • oXygen's Data Source Explorer
  • Transmit

If any of these methods are not working as expected, contact Joe.

Wrap up

Congratulations! Your HSG Development Environment is now up to date!

Clone this wiki locally