The Password Pusher application console (Rails console) provides direct access to your application’s Ruby environment, allowing you to interact with the database, run Ruby code, and perform administrative tasks programmatically.

Overview

The application console is useful for:

  • Administrative tasks - Managing users, administrators, and system settings
  • Data inspection - Querying the database and examining application state
  • Troubleshooting - Debugging issues and testing configurations
  • Custom scripts - Running one-off Ruby code for maintenance or data migration

Note: The console provides direct access to your application and database. Use with caution, especially in production environments.

Prerequisites

  • Docker installed and configured (for Docker installations)
  • Password Pusher container running (for Docker installations)
  • Access to the server where Password Pusher is installed (for non-Docker installations)
  • Appropriate permissions to execute commands

Accessing the Console

If you’re using docker-compose.yml, accessing the console is straightforward:

Method 1: Direct Console Access

Access the console directly without entering the container shell:

docker compose exec pwpush bin/pwpush console

This opens the Rails console immediately.

Method 2: Container Shell Then Console

If you need to run multiple commands or navigate the container first:

# Access the container shell
docker compose exec pwpush bash

# Navigate to the application directory
cd /opt/PasswordPusher

# Start the console
bin/pwpush console

Using Docker Run

If you’re using docker run directly:

Step 1: Find Your Container

List running containers to find your Password Pusher container:

docker ps

Note the container ID or name.

Step 2: Access the Console

Option A: Direct console access

docker exec -it <container_id_or_name> bin/pwpush console

Option B: Container shell then console

# Access the container shell
docker exec -it <container_id_or_name> bash

# Navigate to the application directory
cd /opt/PasswordPusher

# Start the console
bin/pwpush console

Non-Docker Installations

For installations running directly on a server (not in Docker):

# Navigate to your application directory
cd /path/to/PasswordPusher

# Start the console
bin/pwpush console

Or using Rails directly:

bundle exec rails console

Common Console Commands

User Management

Find a User

user = User.find_by(email: 'user@example.com')

Create a User

User.create(
  email: 'user@example.com',
  password: 'secure_password',
  password_confirmation: 'secure_password'
)

Confirm a User Account

user = User.find_by(email: 'user@example.com')
user.confirm

Send Confirmation Email

user = User.find_by(email: 'user@example.com')
user.send_confirmation_instructions

Send Password Reset Email

user = User.find_by(email: 'user@example.com')
user.send_reset_password_instructions

Delete a User

user = User.find_by(email: 'user@example.com')
user.destroy

Warning: Deleting a user is permanent and cannot be reversed. This action is cascading, meaning all pushes owned by that user will also be deleted. Always backup your database before destructive operations.

Administrator Management

Grant Administrator Privileges (Older Versions)

For versions prior to v1.51.2, use these Ruby commands:

PasswordPusher.grant_system_admin!('user@example.com')

Revoke Administrator Privileges (Older Versions)

PasswordPusher.revoke_system_admin!('user@example.com')

Check Administrator Status

user = User.find_by(email: 'user@example.com')
user.admin?  # Returns true if user is an administrator

Note: For versions v1.51.2 and later, use the command-line scripts instead: ./bin/create_admin, ./bin/promote_to_admin, ./bin/demote_admin, ./bin/list_admins

Push Management

Find a Push

push = Push.find_by(url_token: 'abc123')

List Recent Pushes

Push.order(created_at: :desc).limit(10)

Expire a Push Manually

push = Push.find_by(url_token: 'abc123')
push.expired = true
push.save

Delete a Push

push = Push.find_by(url_token: 'abc123')
push.destroy

Database Queries

Count Records

User.count
Push.count

Find Records with Conditions

# Find all administrators
User.where(admin: true)

# Find expired pushes
Push.where(expired: true)

# Find pushes created today
Push.where('created_at >= ?', Date.today)

Environment Variables

The console runs with the same environment variables as your application. If you need to override environment variables for a specific console session:

Note: The syntax in the original document was incorrect. Environment variables should be set before running the console command, not as arguments to it.

Setting Environment Variables (Docker)

# Set environment variable and run console
docker compose exec -e RAILS_ENV=development pwpush bin/pwpush console

# Or set multiple variables
docker compose exec -e RAILS_ENV=development -e DATABASE_URL=sqlite3:db/development.sqlite3 pwpush bin/pwpush console

Setting Environment Variables (Non-Docker)

# Set environment variable and run console
RAILS_ENV=development bin/pwpush console

# Or set multiple variables
RAILS_ENV=development DATABASE_URL=sqlite3:db/development.sqlite3 bin/pwpush console

Exiting the Console

To exit the console, type:

exit

Or press Ctrl+D.

Troubleshooting

Console Won’t Start

Symptoms: Console command fails or hangs.

Solutions:

  1. Check container is running: 
    docker compose ps
# or
docker ps
  2. Check application logs: 
    docker compose logs pwpush

  3. Verify database connectivity: Ensure the database is accessible and DATABASE_URL is correct

  4. Check file permissions: Ensure the application directory is accessible

Database Connection Errors

Symptoms: Console starts but database queries fail.

Solutions:

  1. Verify DATABASE_URL: Check that the database URL is correct 
    docker compose exec pwpush env | grep DATABASE_URL
  2. Check database file exists (SQLite): 
    docker compose exec pwpush ls -la /opt/PasswordPusher/storage/db/
  3. Test database connection (PostgreSQL): 
    docker compose exec pwpush psql $DATABASE_URL -c "SELECT 1;"

Permission Errors

Symptoms: “Permission denied” errors when running commands.

Solutions:

  1. Check container user: Ensure you’re running as the correct user
  2. Verify file ownership: Check that application files are owned by the correct user
  3. Check volume mounts: Ensure volumes are properly mounted with correct permissions

Best Practices

Production Use

  • Backup first: Always backup your database before making changes
  • Test in development: Test console commands in a development environment first
  • Use transactions: Wrap destructive operations in transactions when possible
  • Document changes: Keep notes of what changes you make via the console

Security

  • Limit access: Only grant console access to trusted administrators
  • Audit logs: Review console access logs regularly
  • Use command-line scripts: Prefer built-in scripts (e.g., ./bin/create_admin) over raw Ruby when available

Performance

  • Batch operations: When processing many records, use batch methods: 
    User.find_each do |user|
  # Process user
end
  • Avoid N+1 queries: Use includes to eager load associations: 
    Push.includes(:user).limit(10)

See Also

Updated: