Skip to content

quick-setup.md

Latest commit

 

History

History
197 lines (131 loc) · 4.79 KB

quick-setup.md

File metadata and controls

197 lines (131 loc) · 4.79 KB

Quick Setup Guide

This guide will get Opndrive running on your computer. We'll go step by step, and don't worry if something goes wrong - we've included troubleshooting tips!

Step 1: Download the Code

First, let's get the Opndrive code onto your computer.

# Download the code from GitHub
git clone https://github.com/Opndrive/opndrive.git

# Go into the project folder
cd opndrive

What this does:

  • git clone downloads all the code files to your computer
  • cd opndrive moves you into the project folder

Step 2: Install Dependencies

Now we need to download all the code libraries that Opndrive uses.

# Install main project dependencies
pnpm install

# Go to the frontend folder and install its dependencies
cd frontend
pnpm install

# Go to the s3-api folder and install its dependencies
cd ../s3-api
pnpm install

# Go back to the main folder
cd ..

What this does:

  • Downloads all the JavaScript libraries Opndrive needs
  • Sets up three parts of the project: main, frontend, and s3-api

This might take a few minutes - pnpm is downloading lots of files!

Step 3: Start Opndrive

That's it for setup! Opndrive handles configuration through its user interface, so we don't need to manually edit any files.

Step 4: Start Opndrive

Time to see Opndrive in action!

# Make sure you're in the frontend folder
cd frontend

# Start the development server
pnpm dev

You should see output like:

- ready started server on 0.0.0.0:3000, url: http://localhost:3000

Step 5: Open in Your Browser

Open your web browser and go to: http://localhost:3000

You should see the Opndrive welcome page!

Step 6: Connect Your AWS S3

  1. Click the "Get Started" button in the center of the page

  2. You'll be redirected to /connect - this is Opndrive's setup wizard

  3. Enter your AWS credentials in the simple form:

    • AWS Access Key ID
    • AWS Secret Access Key
    • AWS Region (like us-east-1)
    • S3 Bucket Name

  4. Click "Connect" and Opndrive will:

    • Test your credentials
    • Save them securely in your browser's local storage
    • Redirect you to your dashboard

What You'll See

After connecting successfully:

  • Your personal cloud storage dashboard
  • File and folder browser
  • Upload, download, and file management features
  • All your S3 files and folders displayed beautifully

The best part? Your credentials stay in your browser's local storage - they never leave your computer! and if you click on "User-Icon" > "Clear Session", all your credentials will be removed from local storage.

Next Steps

To Stop Opndrive

In your terminal, press Ctrl+C (or Cmd+C on Mac) to stop the server.

To Start Again Later

cd opndrive/frontend
pnpm dev

To Use with Different AWS Credentials

If you want to switch to a different S3 bucket or AWS account:

  1. Click on the user icon in the top right corner
  2. Select "Clear Session" to remove current credentials
  3. Refresh the page and you will be redirected to home page then click on "Get Started" to redirect to /connect page
  4. Enter new AWS credentials

Don't Have AWS S3 Yet?

No problem! You can:

  1. Create a free AWS account at aws.amazon.com
  2. Create an S3 bucket (there's a free tier)
  3. Get your access keys from the AWS console
  4. Come back and connect through the Opndrive UI

Troubleshooting

"Command not found: pnpm"

  • Make sure you installed pnpm: npm install -g pnpm
  • Restart your terminal and try again

"Port 3000 is already in use"

  • Something else is using port 3000
  • Stop other development servers or change the port:
pnpm dev -- --port 3001

Then go to http://localhost:3001

"Cannot find module" errors

  • Try deleting node_modules and installing again:
rm -rf node_modules
pnpm install

Browser shows "This site can't be reached"

  • Make sure the dev server is running (look for the "ready started server" message)
  • Check you're going to the right URL: http://localhost:3000
  • Try refreshing the page

AWS/S3 connection errors

  • If you see connection errors, double-check your AWS credentials
  • Make sure your S3 bucket exists and your access keys have the right permissions
  • The Opndrive UI will show helpful error messages to guide you

Understanding the Development Server

When you run pnpm dev, you're starting a development server that:

  • Watches your code for changes
  • Automatically reloads the browser when you save files
  • Shows helpful error messages
  • Compiles TypeScript to JavaScript in real-time

This is different from a production server - it's designed to help you develop and test changes quickly.

Congratulations! You now have Opndrive running on your computer!

Next: Learn about Understanding the Code to see how everything works.