Skip to main content
Get DefDrive running locally and make your first authenticated file upload in under 10 minutes.
1

Clone the repository

Clone the DefDrive repository to your local machine:
git clone https://github.com/ankitprasad2005/defdrive.git
cd defdrive
2

Configure environment variables

Create a .env file in the root directory using the example template:
cp .env.example .env
Update the following required variables in your .env file:
.env
# Server Configuration
PORT=5050
HOST_URL=http://localhost:5050
JWT_SECRET=your_secret_key_here

# Database Configuration
POSTGRES_USER=defdrive_user
POSTGRES_PASSWORD=secure_password_here
POSTGRES_DB=defdrive
DB_PORT=5432

# Storage Configuration
DATA_PATH=./data
STORAGE_TYPE=local
Replace JWT_SECRET with a strong random string. This is used to sign authentication tokens.
3

Start the server

docker-compose up --build
The server will start on http://localhost:5050 (or your configured PORT).
Docker Compose automatically sets up PostgreSQL. For local development, ensure you have PostgreSQL installed and running.
4

Create your first user

Register a new user account:
cURL
curl -X POST http://localhost:5050/api/signup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "password": "secure_password",
    "email": "[email protected]",
    "name": "Alice Johnson"
  }'
Response:
{
  "message": "User created successfully",
  "user": {
    "ID": 1,
    "username": "alice",
    "email": "[email protected]",
    "name": "Alice Johnson",
    "MaxFiles": 100,
    "MaxStorage": 1073741824
  }
}
New users get default limits: 100 files and 1GB storage.
5

Login and get your token

Authenticate to receive a JWT token:
cURL
curl -X POST http://localhost:5050/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "password": "secure_password"
  }'
Response:
{
  "message": "Login successful",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": 1,
    "username": "alice",
    "email": "[email protected]",
    "name": "Alice Johnson"
  }
}
Save your token! You’ll need it for all authenticated requests. Tokens expire after 72 hours.
6

Upload your first file

Upload a file using your authentication token:
cURL
curl -X POST http://localhost:5050/api/upload \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -F "file=@/path/to/your/document.pdf"
Response:
{
  "message": "File uploaded successfully",
  "file": {
    "ID": 1,
    "Name": "document.pdf",
    "Location": "alice/document.pdf",
    "Size": 524288,
    "Public": false,
    "UserID": 1
  }
}
Files are stored in DATA_PATH/uploads/username/ by default. The file is private by default.
7

List your files

Retrieve all files in your account:
cURL
curl -X GET http://localhost:5050/api/files \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
Response:
{
  "files": [
    {
      "ID": 1,
      "Name": "document.pdf",
      "Location": "alice/document.pdf",
      "Size": 524288,
      "Public": false,
      "UserID": 1
    }
  ]
}
8

Create a secure access link

Generate a shareable access link with restrictions:
cURL
curl -X POST http://localhost:5050/api/files/1/accesses \
  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client Review Link",
    "expires": "2024-12-31T23:59:59Z",
    "oneTimeUse": false,
    "public": true,
    "ips": [],
    "subnets": [],
    "ttl": 0,
    "enableTTL": false
  }'
Response:
{
  "message": "Access created successfully",
  "access": {
    "ID": 1,
    "Name": "Client Review Link",
    "Link": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "Expires": "2024-12-31T23:59:59Z",
    "OneTimeUse": false,
    "Used": false,
    "FileID": 1
  },
  "link": "http://localhost:5050/link/a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
}
Share the generated link to allow others to access your file securely!

​
Next Steps

Now that you have DefDrive running, explore these features:

Authentication

Learn about JWT tokens and securing your API requests

Access Control

Configure IP restrictions, TTL, and one-time links

File Management

Understand file storage, limits, and organization

API Reference

Explore all available endpoints and parameters

​
Common Issues

Ensure PostgreSQL is running and the DATABASE_URL or individual database environment variables are correctly set in your .env file.For Docker Compose, the database service must be healthy before the app starts. Check logs:
docker-compose logs db
Check your current usage and limits:
curl -X GET http://localhost:5050/api/user/limits \
  -H "Authorization: Bearer YOUR_TOKEN_HERE"
Default limits are 100 files and 1GB storage. See User Limits to adjust these values.
JWT tokens expire after 72 hours (configured in controllers/user.go:80). Login again to get a fresh token:
curl -X POST http://localhost:5050/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "alice", "password": "secure_password"}'
Need more help? Check the Installation Guide or explore the API Reference for detailed endpoint documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us