Installation

Installation Guide

This guide will walk you through setting up NQ on your computer, step-by-step. Even if you're not a developer, you can follow these instructions to get NQ running.

Time needed: 30 minutes to 2 hours (depending on experience level)

What you'll do:

1. Install required software (Go, Node.js, and a database)
2. Download NQ
3. Set up the backend (the "brain" of NQ)
4. Set up the frontend (the mobile app)
5. Start using NQ!

Step 1: Install Required Software

Before NQ can run, you need to install three programs. Don't worry - they're all free!

Install Go (Programming Language)

Go powers NQ's backend server.

What to do:

1. Visit https://go.dev/dl/
2. Download the installer for your operating system:
   • Windows: Download the .msi file
   • Mac: Download the .pkg file
   • Linux: Download the appropriate tarball
3. Run the installer and follow the on-screen instructions
4. Accept the default installation options

Verify it worked:

• Open Terminal (Mac/Linux) or Command Prompt (Windows)
• Type: go version
• You should see something like: go version go1.25.1

Install Node.js (JavaScript Runtime)

Node.js runs the mobile app development server.

What to do:

1. Visit https://nodejs.org/
2. Download the LTS (Long Term Support) version - this is the recommended, stable version
3. Run the installer
4. Follow the installation wizard (accept default options)

Verify it worked:

• Open Terminal/Command Prompt
• Type: node --version
• You should see a version number like: v18.x.x or higher

Set Up Neo4j Database

Neo4j is a special type of database that stores connections between your media (like "this movie is similar to that one").

Choose one option:

Option A: Neo4j Aura (Cloud) - Recommended for beginners

This is easier because nothing installs on your computer.

What to do:

1. Go to https://neo4j.com/cloud/aura/
2. Click "Start Free"
3. Create an account (or sign in with Google)
4. Click "Create Instance" → Select "Free" tier
5. IMPORTANT: Save the credentials shown! You'll need:
   • Connection URI (looks like: neo4j+s://xxxxx.databases.neo4j.io)
   • Username (usually neo4j)
   • Password (auto-generated)
6. Click "Download and Continue" to save these to a text file
7. Wait 1-2 minutes for your database to start

Option B: Neo4j Desktop (Local) - For advanced users

Install the database on your computer.

What to do:

1. Go to https://neo4j.com/download/
2. Download Neo4j Desktop for your operating system
3. Install and open Neo4j Desktop
4. Create a new project (name it "NQ")
5. Add a new "Local DBMS" (database)
6. Set a password you'll remember
7. Click "Start" to run your database
8. Your credentials are:
   • Connection URI: bolt://localhost:7687
   • Username: neo4j
   • Password: [your chosen password]

Step 2: Clone NQ

git clone https://github.com/grillinr/nq.git

cd nq

Step 3: Set Up the Backend

3.1: Navigate to the Backend Folder

cd backend

3.2: Create Your Configuration File

Mac/Linux:

cp .envtemplate .env

Windows:

copy .envtemplate .env

3.3: Add Your Database Credentials

What to do:

1. Open the .env file
2. Find these lines:

   NEO4J_URI=
   NEO4J_USERNAME=
   NEO4J_PASSWORD=
   NEO4J_DATABASE=

3. Fill in your Neo4j credentials from Step 1:

   NEO4J_URI=neo4j+s://xxxxx.databases.neo4j.io  # Your connection URI from Aura
   NEO4J_USERNAME=neo4j                           # Usually just "neo4j"
   NEO4J_PASSWORD=YourPasswordHere                # The password you saved
   NEO4J_DATABASE=neo4j                          # Usually just "neo4j"

4. Save the file

3.4: Test the Backend

go run .

If you see errors:

• "Failed to connect to Neo4j" → Check your credentials in .env
• "Port 8080 already in use" → Close other programs using that port

3.5: Verify It's Working

While the backend is running:

1. Open a web browser
2. Go to: http://localhost:8080
3. You should see a page called "GraphQL Playground"

Step 4: Set Up the Frontend

4.1: Navigate to the Frontend Folder

Open a new terminal window:

cd nq-frontend

4.2: Install Dependencies

npm install

4.3: Start the Development Server

npx expo start

4.4: Open the App

Option A: On Your Phone (Easiest)

1. Install the "Expo Go" app from your phone's app store (it's free)
2. Open Expo Go
3. Scan the QR code shown in your terminal
4. Wait for the app to load (first time takes a minute)

Option B: Android Emulator

1. Install Android Studio
2. Set up an Android Virtual Device (AVD) - see Android setup guide
3. Start the emulator
4. In the Expo terminal, press a

Option C: iOS Simulator (Mac only)

1. Install Xcode from the Mac App Store
2. In the Expo terminal, press i
3. The simulator will open and load the app

Option D: Web Browser (Limited)

1. In the Expo terminal, press w
2. A browser window opens (note: some features won't work in browser)

Step 5: Verify Everything Works

Test the Full System

To use NQ, you need both running at the same time:

• Terminal 1: Backend (cd backend && go run .)
• Terminal 2: Frontend (cd nq-frontend && npx expo start)

Keep both terminal windows open while using NQ.

Next Steps

1. Connect Your Services

   • See the API Data Sources guide
   • Get API keys for services you want to use
   • Add them to your .env file

2. Learn to Use NQ

   • Read the User Guide for detailed instructions
   • Start syncing your media libraries
   • Get personalized recommendations!

3. Explore the Features

   • Try the GraphQL Playground at http://localhost:8080
   • Browse your media library in the app
   • Discover new content based on your preferences