Password Reset Without SMTP

This guide provides detailed instructions on how to reset a user password directly inside the Docker container for Palmr, without requiring SMTP configuration. This method is particularly useful for administrators who do not have email services set up or need to regain access to accounts in emergency situations.

When and why to use this method

Resetting a password without SMTP is an alternative approach for specific scenarios where the standard email-based reset is not feasible. Consider using this method if:

• An admin user is locked out and cannot access their email for a password reset.
• SMTP services are not configured or are experiencing issues.
• You need to perform emergency system recovery and restore access quickly.
• You are setting up an initial environment and need to configure accounts.
• You are conducting controlled testing in a development setup.

Warning: This process bypasses the normal email-based password reset mechanism, which could pose a security risk if not handled properly. Use this method only when necessary, ensure it is performed by trusted administrators, and always document the reason for the reset.

How the password reset works

Palmr provides a CLI script that allows administrators to reset passwords directly within the Docker container. This script is designed to maintain security by enforcing interactive confirmation at every step, validating input data, and securely encrypting the new password using bcrypt with 10 salt rounds (consistent with the system's security standards). The script does not send email notifications, log invalid login attempts, or alter other user settings—it focuses solely on password reset.

Step-by-step instructions

Follow these steps to reset a user password using the provided script. Ensure you have access to the Docker container before proceeding.

1. List Docker containers and identify the correct one

Before accessing the Palmr container, you need to identify its name or ID. Open a terminal on your host machine and list all running Docker containers by running the following command:

docker ps

This command will display a list of active containers, including their names, IDs, images, and other details. Look for the container running the Palmr application. If you used a specific name when setting up the container (e.g., palmr-app), it will appear under the NAMES column. If no name was specified, note the CONTAINER ID (a short string of characters) for the container associated with the Palmr image (likely something like palmr or a custom image name).

Note: If you don't see the Palmr container, ensure it is running. You can start it using docker start <container_name_or_id> if it's stopped. If you're unsure about the setup, refer to the Palmr installation guide.

2. Access the Docker container

Once you've identified the correct container, access it by running the following command:

docker exec -it <container_name_or_id> /bin/sh

Replace <container_name_or_id> with the name or ID of your Palmr container. This command opens an interactive shell session inside the container, allowing you to execute commands directly.

3. Navigate to the server directory

Once inside the container, navigate to the server directory where the reset script is located:

cd /app/server

This directory contains the necessary scripts and configurations for managing Palmr's backend operations.

4. Run the password reset script

Execute the password reset script to start the interactive process:

./reset-password.sh

The script will prompt you to enter the email address of the user whose password you wish to reset. It will then display the user's information for verification, ask for confirmation to proceed, and request a new password (minimum 8 characters) which must be entered twice to ensure accuracy. Each step requires explicit confirmation to prevent accidental changes.

Note: If you need to see a list of all users in the system before proceeding, you can run ./reset-password.sh --list. For additional help, use ./reset-password.sh --help.

Example session

Below is an example of how the interactive session might look when running the script:

$ ./reset-password.sh

Palmr Password Reset Tool
===============================
This script allows you to reset a user's password directly from the Docker terminal.
WARNING: This bypasses normal security checks. Use only when necessary!

Enter user email: user@example.com

User found:
   Name: John Smith
   Username: john.smith
   Email: user@example.com
   Status: Active
   Admin: No

Do you want to reset the password for this user? (y/n): y

Enter new password requirements:
   - Minimum 8 characters

Enter new password: ********
Confirm new password: ********

Hashing password...
Updating password in database...
Cleaning up existing password reset tokens...

Password reset successful!
   User: John Smith (user@example.com)
   The user can now login with the new password.

Security Note: The password has been encrypted using bcrypt with 10 salt rounds.

Troubleshooting common issues

If you encounter issues while running the script, refer to the following solutions to resolve common problems:

• Error: "tsx is not available"
  This error indicates missing dependencies. The script will attempt to install them automatically, but if it fails, manually install them by running:

  pnpm install
  # or
  npm install

• Error: "Prisma client not found"
  This error occurs if the Prisma client is not generated. The script should handle this automatically, but if it fails, generate it manually with:

  npx prisma generate

• Error: "Database connection failed"
  If the script cannot connect to the database, check the following:

  • Ensure the database service is running within the container.
  • Confirm that the prisma/palmr.db file exists and has the correct permissions.
  • Verify that the container has access to the database volume.

• Error: "Script must be run from server directory"
  This error appears if you are not in the correct directory. Navigate to the server directory with:

  cd /app/server

• Error: "User not found"
  If the email provided does not match any user, double-check the email address. You can list all users to find the correct one by running:

  ./reset-password.sh --list

  Ensure the user exists in the system before attempting the reset.

• Error: "Password does not meet requirements"
  The new password must be at least 8 characters long. Ensure it meets this requirement and re-enter it carefully, confirming it matches the second entry.

• Error: "Confirmation does not match"
  If the two password entries do not match, the script will prompt you to try again. Ensure both entries are identical.

• General Script Failure or Unexpected Behavior
  If the script fails for an unknown reason, check the error message for details. Ensure your Palmr installation is up to date, and consider restarting the container if there are transient issues. If problems persist, consult the Palmr documentation or community for additional support.

Security and best practices

To maintain the integrity and security of your Palmr instance while using this password reset method, adhere to the following guidelines:

• Interactive Confirmation: The script enforces interactive mode, requiring explicit confirmation at each step to prevent unauthorized or accidental resets. There are no shortcuts or automated options.
• Access Restriction: Only administrators with direct access to the Docker container can use this script, ensuring that unauthorized users cannot reset passwords.
• Password Encryption: New passwords are encrypted using bcrypt with 10 salt rounds, matching Palmr's standard security practices.
• Documentation and Notification: Always document the date, time, and reason for performing a password reset. Notify the affected user through alternative means (if possible) to inform them of the change.
• Backup Recommendation: Before using this script in a production environment, consider backing up your database to prevent data loss in case of an error.
• Post-Reset Actions: After resetting a password, verify that the user can log in successfully and check system logs for any unusual activity related to the reset.
• Limit Usage: Use this method sparingly and only in situations where SMTP-based reset is not an option. It is not intended for routine password management.
• Secure Environment: Ensure that access to the Docker container and host machine is secured with strong passwords, restricted permissions, and, if possible, two-factor authentication to prevent unauthorized access to administrative tools.

Tip: Treat this method as a last resort. Whenever possible, configure SMTP to enable the standard email-based password reset process, which provides an additional layer of security and user verification.

Security philosophy

This script is built with a strong focus on security, prioritizing mandatory interactivity, multiple confirmations, and strict input validation. There are no "quick modes" or bypass options—every password reset requires careful and deliberate action from the administrator to ensure accountability and minimize risks.