Initial Hyku Setup

This guide walks you through the steps to get a docker-based development environment running locally. We've condensed the instructions for Hyku and HykuKnapsack to get you going quickly with a base development environment we can use to explore Hyku and experiment with new features.

Goals:

• Start the Hyku admin application
• Create the first Administrator account
• Create the first Tenant site

Prerequisites

• Rails 3.x installed on your local system
• Docker Desktop v4.x
• Git command line tools (e.g. git clone)

Lesson

1. Get a local copy of the application.

   git clone --recurse https://github.com/RepoCamp/pitt2025.git
   

2. Change your working directory to the new project directory

   cd pitt2025
   

3. Add the main HykuKnapsack repo as an alternate git remote

   git remote add prime https://github.com/samvera-labs/hyku_knapsack
   

4. Make sure we have a local copy of the magic branch for HykuKnapsack to run bundle install correctly

   git branch required_for_knapsack_instances 5a7c54c
   

5. Enable the [flexible metadata] feature

   echo "HYRAX_FLEXIBLE=true" >> .env.development
   

6. Install the StackCar gem to help manage your containers and create a private development network.

   gem install stack_car
   

7. Set up a local network and TLS certificate (so we can use HTTPS locally).
   During this step, you'll be prompted for an unzip password - use localhost, then you'll be prompted for your local system password to add the certificate to your local keychain.

   sc proxy cert
   sc proxy up
   

8. Start up Hyku
   This will download docker images and create containers for all of your application components. The first time you run build and up, they can take up to 15 minutes on a 100Mbit connection. Please be patient, especially if you are on a slower connection. After the initial load, starting and stopping the application takes under a minute.

   sc build
   sc up
   

9. Open the Hyku admin application in your browser.
   *Watch for the message web-1 | * Listening on 0.0.0.0:3000. Once you see this message, you can access the admin app in your browser.

   Visit https://admin-pitt2025.localhost.direct/

10. Create a new super-admin user from the command line. From a new terminal session in the pitt2025 directory, run: Enter the e-mail and password for your new administrator when prompted.

    sc exec rake hyku:superadmin:create
    

11. Log-in to the admin app in your browser.
    Use the e-mail and password you just supplied to login

    Click on the "Administrator login" link at the bottom of the Hyku homepage.
    -OR-
    Visit https://admin-pitt2025.localhost.direct/users/sign_in.

12. Create your first Hyku Tenant.
    A tenant is an isolated repository that can be managed and searched independently from other tenants running on the same Hyku host.

    • Click on the "Accounts" link in the upper right navigation bar
    • Click on the "Create new account" button
    • Enter a name for your first repository; we've used "sandbox" for the following lessons
    • Click on the "Save" button to create your repository site
    • Click on the "Cancel" link to return to the Account overview
    • Copy the Tenant UUID and CName values. We will need these in future lessons
      

13. Disable HTTP authentication for the repository.

    • On the "Accounts" page for your new repository, click the "Edit" link
    • On the "Editing Account" page, check the "Is Public" button. This just disables HTTP Basic authentication on the site; it does not make the site publicly available.
    • Note the "Primary Domain Name" field: this should match the CName from the previous step.
    • Scroll down, and click on the "Save Changes" at the bottom of the page

14. Log-in to the new repository.

    • Visit the address from the previous step in your browser. e.g https://sandbox-pitt2025.localhost.direct
    • Login using your super-admin credentials.
    • You should now see the administrator dashboard for your repository.

Review

Congratulations! You have successfully set up a local Hyku application using Docker and HykuKnapsack. In this lesson, we

• Cloned a local copy of the Hyku codebase
• Started the Hyku Tenant (aka Account) administration app
• Created a super-admin user that can create and manage tenants
• Created our first Hyku repository (aka Tenant)
• Logged into our tenant using the super-admin credentials