PutPlace Client Quick Start

This guide shows you how to quickly start using the PutPlace client to scan and upload files.

Prerequisites

  1. PutPlace server running (see main README.md for setup)

  2. User account (get credentials from server administrator)

Getting Account Credentials

Option 1: Ask Server Administrator

Request a username and password from your PutPlace server administrator.

Option 2: Use Admin Account (if you have server access)

The admin account is automatically created on first server startup. Check the server logs or /tmp/putplace_initial_creds.txt for the auto-generated credentials.

Option 3: Register New User (if registration is enabled)

# Register via API
curl -X POST http://localhost:8000/api/register \
  -H "Content-Type: application/json" \
  -d '{"username": "myuser", "email": "user@example.com", "password": "secure-password"}'

Using the Client

The client supports three ways to provide your credentials:

Method 1: Command Line (Quick Testing)

python pp_client.py /path/to/scan --username "admin" --password "your-password"

Pros: Quick and easy for testing Cons: Credentials visible in shell history and process list

Configuration Priority

If you specify credentials in multiple places, the priority is:

  1. Command line (--username/--password) - Highest priority

  2. Environment variables (PUTPLACE_USERNAME/PUTPLACE_PASSWORD)

  3. Config file (~/pp_client.conf or pp_client.conf) - Lowest priority

Complete Examples

Example 1: Scan Local Directory

# Using environment variables
export PUTPLACE_USERNAME="admin"
export PUTPLACE_PASSWORD="your-password"
python pp_client.py /var/log

Example 2: Scan with Exclusions

python pp_client.py /home/user \
  --exclude ".git" \
  --exclude "node_modules" \
  --exclude "*.log"

Example 3: Scan Remote Server

python pp_client.py /var/www \
  --url "https://putplace.example.com/put_file" \
  --username "admin" \
  --password "production-password"

Example 4: Dry Run (Test Without Sending)

# See what would be sent without actually sending
python pp_client.py /path/to/scan --dry-run

Example 5: Using Config File

~/pp_client.conf:

[DEFAULT]
url = https://putplace.example.com/put_file
username = admin
password = your-password
exclude = .git
exclude = node_modules
exclude = *.log

Run:

# All settings loaded from config file
python pp_client.py /var/www

Security Best Practices

✅ DO:

  1. Protect your credentials

    # Config file permissions
chmod 600 ~/pp_client.conf

# Never commit passwords
# pp_client.conf is already in .gitignore

  2. Use separate accounts per client

    • One account per server

    • One account per application

    • Easier to manage access

  3. Use strong passwords

    • At least 8 characters

    • Mix of letters, numbers, symbols

    • Use password manager to generate

❌ DON’T:

  1. Don’t commit passwords to version control

    • pp_client.conf is in .gitignore

    • Never put passwords in code

  2. Don’t share passwords

    • Create separate accounts for each user/server

  3. Don’t use command line in production

    • Credentials visible in process list

    • Use config file or environment variable

Troubleshooting

“Both username and password are required”

✗ Both username and password are required for authentication

Solution: Provide both credentials via:

  • --username and --password flags

  • PUTPLACE_USERNAME and PUTPLACE_PASSWORD environment variables

  • username and password in ~/pp_client.conf

“Login failed: 401”

✗ Login failed: 401
  Incorrect username or password

Possible causes:

  1. No credentials provided

  2. Invalid username or password

  3. User account disabled

Solution:

# Test your credentials
curl -X POST http://localhost:8000/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your-password"}'

# If you forgot password, contact server admin to reset

“Config file not found”

The client looks for config files in this order:

  1. pp_client.conf (current directory)

  2. ~/pp_client.conf (home directory)

  3. Path specified with --config

Create one:

cp pp_client.conf.example ~/pp_client.conf
chmod 600 ~/pp_client.conf
nano ~/pp_client.conf

Common Workflows

Development Setup

# 1. Get credentials from server admin
export PUTPLACE_USERNAME="dev-user"
export PUTPLACE_PASSWORD="dev-password"

# 2. Test connection
python pp_client.py /tmp --dry-run

# 3. Scan actual directory
python pp_client.py /home/user/projects

Production Server Setup

# 1. Create config file
cat > ~/pp_client.conf << 'EOF'
[DEFAULT]
url = https://putplace.example.com/put_file
username = prod-user
password = production-password
exclude = .git
exclude = *.log
exclude = tmp
EOF

# 2. Set secure permissions
chmod 600 ~/pp_client.conf

# 3. Test
python pp_client.py /var/www --dry-run

# 4. Run for real
python pp_client.py /var/www

# 5. Set up cron job
echo "0 2 * * * /usr/bin/python3 /path/to/pp_client.py /var/www" | crontab -

Multi-Environment Setup

# Development
cat > ~/pp_client.conf.dev << 'EOF'
url = http://dev-putplace:8000/put_file
username = dev-user
password = dev-password
EOF

# Production
cat > ~/pp_client.conf.prod << 'EOF'
url = https://putplace.example.com/put_file
username = prod-user
password = prod-password
EOF

# Use with --config flag
python pp_client.py /var/www --config ~/pp_client.conf.prod

Getting Help

# Show all options
python pp_client.py --help

# Check version and settings
python pp_client.py --version

Next Steps

  • 📖 Read Authentication Guide for JWT token management

  • 📚 Check Client Guide for comprehensive usage

  • 🔒 Review Security Guide for best practices