Skip to content

Update

Jump to bottom
Joe Wicentowski edited this page Apr 10, 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 About This Mac. Select the Software Update button and install any available software updates. If you are running a version of macOS lower than 11 (Big Sur), Apple's macOS Big Sur webpage lists requirements and instructions for upgrading.

  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. Install nvm, a utility for installing and managing versions of Node.JS:

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

  3. 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 nvm's settings take effect before the next commands.

  4. In the new Terminal window, install our required version of Node.JS and two Node.JS-based dependencies:

     nvm install 17.6.0

 npm install -g gulp bower

  5. 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.)

  6. 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.

Set up eXist

  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 Pull updates from all repositories.

  4. From the External Tools toolbar menu, select these, one by one, waiting for them to complete before proceeding:

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

  5. 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. Once the splash screen disappears, you can start, stop, and quit eXist and access other eXist utilities via its menu bar entry (a blue "X"-shaped icon).

  6. 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.

  7. 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