Skip to main content

​
Overview

This guide will walk you through setting up the PrivyCode backend server, a Go-based API that enables secure, read-only sharing of private GitHub repositories through expiring viewer links.

​
Prerequisites

Before you begin, ensure you have the following installed:

Go 1.23+

Download from golang.org

PostgreSQL

Version 12 or higher

Git

For cloning the repository
You’ll also need to create a GitHub OAuth App to enable authentication. We’ll cover this in the setup steps.

​
Installation

1

Clone the Repository

Clone the PrivyCode server repository to your local machine:
git clone https://github.com/greatdaveo/privycode-server
cd privycode-server
2

Install Dependencies

Install all Go dependencies using Go modules:
go mod tidy
This will download all required packages including GORM, godotenv, and PostgreSQL drivers as specified in go.mod.
3

Create GitHub OAuth App

To enable GitHub authentication, you need to create a GitHub OAuth application:
  1. Go to GitHub Developer Settings
  2. Click “New OAuth App”
  3. Fill in the application details:
    • Application name: PrivyCode (or your preferred name)
    • Homepage URL: http://localhost:8080
    • Authorization callback URL: http://localhost:8080/github/callback
  4. Click “Register application”
  5. Note down your Client ID and generate a Client Secret
Keep your Client Secret secure! Never commit it to version control.
4

Setup PostgreSQL Database

Create a new PostgreSQL database for PrivyCode:
# Login to PostgreSQL
psql -U postgres

# Create database
CREATE DATABASE privycode;

# Exit psql
\q
Your database URL will look like:
postgresql://username:password@localhost:5432/privycode
5

Configure Environment Variables

Create a .env file in the project root with the following configuration:
.env
PORT=8080
DATABASE_URL=postgresql://username:password@localhost:5432/privycode
GITHUB_CLIENT_ID=your_github_client_id
GITHUB_CLIENT_SECRET=your_github_client_secret
GITHUB_CALLBACK_URL=http://localhost:8080/github/callback
GO_ENV=development
FRONTEND_URL=http://localhost:5173
MOBILE_URL=http://localhost:5173
VariableDescriptionExample
PORTServer port number8080
DATABASE_URLPostgreSQL connection stringpostgresql://user:pass@localhost:5432/privycode
GITHUB_CLIENT_IDOAuth app client ID from GitHubIv1.a1b2c3d4e5f6g7h8
GITHUB_CLIENT_SECRETOAuth app client secret from GitHuba1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0
GITHUB_CALLBACK_URLOAuth callback URLhttp://localhost:8080/github/callback
GO_ENVEnvironment modedevelopment or production
FRONTEND_URLFrontend application URLhttp://localhost:5173
MOBILE_URLMobile application URLhttp://localhost:5173
Replace the placeholder values with your actual credentials. The .env file is git-ignored by default.
6

Run Database Migrations

Uncomment the migration line in cmd/server/main.go to create the database schema:
cmd/server/main.go
func main() {
    // To Connect to the DB
    config.ConnectDB()

    // For auto migrate to DB
    config.RunMigrations() // Uncomment this line

    // To set up HTTP router
    mux := http.NewServeMux()
    // ... rest of the code
}
Then run the server once to execute migrations:
go run cmd/server/main.go
You should see:
Connected to PostgreSQL successfully!!!
Migrations completed successfully
Server starting on :8080...
After the first run, you can comment out config.RunMigrations() again to avoid running migrations on every startup.
The migration creates two tables:
  • users - Stores GitHub authenticated users
  • viewer_links - Stores shareable repository links with expiration and view limits
7

Start the Server

Run the server in development mode:
go run cmd/server/main.go
For production, build and run the binary:
# Build the binary
go build -o privycode-server cmd/server/main.go

# Run the binary
./privycode-server
Server is now running on http://localhost:8080

​
Testing Your Setup

Verify that your server is running correctly: 
curl http://localhost:8080/test

​
Test GitHub OAuth Flow

1

Initiate OAuth

Visit the login endpoint in your browser:
http://localhost:8080/github/login
This will redirect you to GitHub for authorization.
2

Authorize Application

Authorize the PrivyCode application on GitHub.
3

Get Your Token

After successful authorization, you’ll be redirected to the callback URL with a token in the query parameters.

​
Test Authenticated Endpoints

Once you have a token, test the authenticated endpoints: 
curl -H "Authorization: Bearer YOUR_TOKEN_HERE" \
     http://localhost:8080/me

​
API Endpoints Overview

Here’s a quick reference of the available endpoints:

​
Authentication Endpoints

MethodEndpointDescriptionAuth Required
GET/testHealth check endpointNo
GET/github/loginInitiate GitHub OAuth flowNo
GET/github/callbackGitHub OAuth callbackNo
GET/meGet current user infoYes
MethodEndpointDescriptionAuth Required
GET/dashboardGet all viewer linksYes
POST/generate-viewer-linkCreate new viewer linkYes
PUT/update-link/:idUpdate existing linkYes
DELETE/delete-link/:idDelete viewer linkYes

​
Public Viewer Endpoints

MethodEndpointDescriptionAuth Required
GET/view/:tokenView repository contentsNo
GET/view-files/:token/file?path=View specific fileNo
GET/view-folder/:token?path=Browse foldersNo
GET/view-info/:tokenGet repository infoNo
All authenticated endpoints require the Authorization: Bearer <token> header. See Authentication for more details.

​
Project Structure

Understanding the codebase structure: 
privycode-server/
├── cmd/
│   └── server/
│       └── main.go              # Application entry point
├── config/
│   └── config.go                # Database configuration and migrations
├── internal/
│   ├── handlers/                # HTTP request handlers
│   │   ├── auth_handler.go      # GitHub OAuth handlers
│   │   ├── dashboard_handler.go # Dashboard endpoint
│   │   ├── me_handler.go        # User info endpoint
│   │   └── viewer_handler.go    # Viewer link handlers
│   ├── middleware/              # HTTP middleware
│   │   ├── auth.go              # Authentication middleware
│   │   └── cors.go              # CORS middleware
│   ├── models/                  # Data models
│   │   ├── user.go              # User model
│   │   └── viewer_link.go       # ViewerLink model
│   ├── routes/
│   │   └── router.go            # Route definitions
│   ├── github/
│   │   └── oauth.go             # GitHub API integration
│   └── utils/
│       └── token.go             # Token utilities
├── .env.example                 # Environment variables template
├── go.mod                       # Go module dependencies
└── README.md

​
Next Steps

API Reference

Explore the complete API documentation

Authentication

Learn about OAuth and token management

Viewer Links

Understand how viewer links work

Deployment

Deploy to production

​
Troubleshooting

Error: Error connecting to DBSolutions:
  • Verify PostgreSQL is running: pg_isready
  • Check your DATABASE_URL format is correct
  • Ensure the database exists: psql -l | grep privycode
  • Verify credentials have proper permissions
Error: GitHub redirects fail or show errorsSolutions:
  • Verify GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are correct
  • Check GITHUB_CALLBACK_URL matches your GitHub OAuth app settings
  • Ensure callback URL is http://localhost:8080/github/callback for local development
  • Verify your GitHub OAuth app is not suspended
Error: bind: address already in useSolutions:
  • Change the PORT in your .env file
  • Kill the process using port 8080: lsof -ti:8080 | xargs kill -9
Error: Tables not created in databaseSolutions:
  • Ensure config.RunMigrations() is uncommented in cmd/server/main.go
  • Check database connection is successful before migrations run
  • Verify GORM AutoMigrate logs in console output
  • Manually check tables: psql -d privycode -c "\dt"

​
Need Help?

GitHub Issues

Report bugs or request features

Developer

Contact the maintainer

Build docs developers (and LLMs) love

Get started for freeTalk to us