# Installation

This guide walks you through setting up the OrchardGo project on your local machine.

## Prerequisites

Before installing, ensure you have completed all steps in [Prerequisites](./prerequisites.md).

## Step 1: Clone the Repository

```bash
git clone https://github.com/theorchard/orchardgo.git
cd orchardgo
```

## Step 2: Configure Private Repositories

OrchardGo uses private npm packages that require authentication.

### Create GitHub Token

1. Follow the instructions in [The Orchard's JavaScript Packages Guide](https://github.com/theorchard/docs/blob/master/javascript/packages.md)
2. Create a personal access token with `read:packages` permission

### Configure .npmrc

```bash
# Copy the template
cp ./setup/.npmrc.shadow .npmrc

# Edit .npmrc and insert your tokens
# The file contains placeholders for:
# - GitHub token
# - Any other private registry tokens
```

## Step 3: Environment Configuration

```bash
# Copy the environment template
cp .env.shadow .env

# Edit .env with your configuration
# See configuration.md for details on each variable
```

For detailed environment variable documentation, see [Configuration](./configuration.md).

## Step 4: Clean Install

```bash
# Clean any previous installations
yarn clean

# Reset the project
yarn reset

# Install all dependencies
yarn install
```

### What Happens During Installation

The `yarn install` command:
- Installs npm dependencies
- Runs `postinstall` scripts
- Installs iOS pods (via `cd ios && pod install`)
- Applies necessary patches via `patch-package`

## Step 5: Verify Installation

```bash
# Check that all tools are correctly installed
yarn check:tools

# Run tests to verify setup
yarn test
```

## Platform-Specific Setup

### iOS Setup

1. Open the workspace in Xcode:
   ```bash
   yarn xcode
   ```

2. Configure signing:
   - Select the project in Xcode
   - Go to "Signing & Capabilities"
   - Select your team

3. Install iOS simulator (if needed):
   - Open Xcode → Preferences → Components
   - Download the iOS version you need

### Android Setup

1. Open Android Studio
2. Configure SDK:
   - Tools → SDK Manager
   - Install required SDK versions

3. Create an emulator:
   - Tools → AVD Manager
   - Create Virtual Device
   - Select a device definition and system image

## Common Issues

### Pod Install Fails

```bash
# Clean pod cache and reinstall
cd ios
rm -rf Pods Podfile.lock
pod install --repo-update
```

### Node Modules Issues

```bash
# Complete clean reinstall
yarn clean
rm -rf node_modules yarn.lock
yarn install
```

### Permission Errors

If you encounter permission errors with CocoaPods:
```bash
# Try installing without sudo
export GEM_HOME=$HOME/.gem
export PATH=$GEM_HOME/bin:$PATH
gem install cocoapods --user-install
```

### Metro Bundler Issues

```bash
# Reset Metro bundler
yarn reset
```

## Next Steps

- [Running the App](../development/running-the-app.md)
- [Configuration Details](./configuration.md)
- [Development Workflow](../development/)

## Additional Resources

- [Troubleshooting Guide](../development/debugging.md)
- [Scripts Reference](../development/scripts-reference.md)