Prerequisites#

Ensure Docker and Docker Compose are installed on your Linux server. All other dependencies (Ruby, Rails, PostgreSQL, Redis) are managed within the containers and do not require manual installation.

Environment Configuration#

CipherSwarm requires several environment variables for proper operation. You can set these in your shell or, preferably, in a .env file in the project root.

A template .env.example file is provided in the repository with all available configuration options. Copy this file to .env and customize it for your environment.

The critical required variables are:

RAILS_MASTER_KEY=your_rails_master_key
POSTGRES_PASSWORD=your_postgres_password # Required; enforced via docker-compose validation
APPLICATION_HOST=your_application_host # Required for mailer configuration and DNS rebinding protection
TUSD_HOOK_SECRET=your_tusd_hook_secret # Required in production to authenticate tusd webhook requests

Replace your_rails_master_key with the actual master key for your Rails application. If you do not have one, generate it with:

openssl rand -hex 32

Set POSTGRES_PASSWORD to a strong password for the PostgreSQL database. The container will fail to start in production if this is not set.

Set APPLICATION_HOST to your application's base URL without the protocol (e.g., cipherswarm.example.com). This is required for email links, password resets, and redirects to function correctly. In production, this variable also provides DNS rebinding protection.

Set TUSD_HOOK_SECRET to a cryptographically random value to authenticate webhook requests from the tusd upload service. This prevents cache poisoning attacks via unauthenticated POST requests. Generate it with:

openssl rand -hex 32

Important: In production environments, both APPLICATION_HOST and TUSD_HOOK_SECRET are strictly enforced. The application will fail to start if they are not set.

For complete details on all environment variables, their purposes, defaults, and validation requirements, see the Environment Variables Reference.

Storage Configuration#

By default, CipherSwarm uses local disk storage. All data is persisted in Docker volumes and does not require additional services.

For production deployments requiring S3-compatible storage (AWS S3, MinIO, SeaweedFS, etc.), you can opt in by setting these environment variables:

ACTIVE_STORAGE_SERVICE=s3
AWS_ACCESS_KEY_ID=your_access_key
AWS_SECRET_ACCESS_KEY=your_secret_key
AWS_REGION=us-east-1 # Optional; defaults to 'us-east-1'
AWS_BUCKET=application # Optional; defaults to 'application'
AWS_ENDPOINT=https://s3.example.com # Required for non-AWS S3-compatible services
AWS_FORCE_PATH_STYLE=true # Optional; set to 'true' for MinIO/path-style URLs

Setup Steps#

1. Clone the CipherSwarm repository:

   ⧉

   git clone https://github.com/unclesp1d3r/CipherSwarm.git
   cd CipherSwarm
   

2. Create a .env file in the project root using the provided template:

   ⧉

   cp .env.example .env
   

   Edit the .env file and set the required environment variables as described above.

3. Start the server stack with Docker Compose:

   ⧉

   docker compose up
   

   By default, this command uses the docker-compose.yml file in the repository root, which defines services for the Rails web server, PostgreSQL, Redis, and Sidekiq background jobs. All data is persisted using host bind mounts and named Docker volumes.

   If you want to use the production configuration, use:

   ⧉

   docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
   

   (Ensure that docker-compose.prod.yml exists and is configured as needed.)

Database Preparation#

For initial setup or after upgrading to a version with database schema changes, you must prepare the database before starting the application. Database migrations are controlled by the RUN_DB_PREPARE environment variable to prevent migration races in scaled deployments where multiple replicas might try to migrate simultaneously.

To run database migrations:

docker compose run --rm -e RUN_DB_PREPARE=true web ./bin/rails db:prepare

After database preparation completes successfully, start or restart your application containers:

docker compose up -d

Scaling Considerations: For production deployments with multiple web container replicas, always run database migrations once using RUN_DB_PREPARE=true on a single instance before starting additional replicas. Regular web containers should not have RUN_DB_PREPARE=true set to avoid concurrent migration attempts.

Accessing the Application#

Once all containers are running, access the CipherSwarm web interface at http://localhost:80 (or your server's IP address on port 80).

Log in with the default admin credentials:

• Username: admin
• Password: password

Change the admin password immediately after logging in for the first time.

Data Persistence#

CipherSwarm stores persistent data in host bind mounts under the project directory:

• PostgreSQL data: ./postgres-data/
• Redis data: ./redis-data/
• Application storage: ./storage/

These directories are created automatically when the containers start and are excluded from Git. Include these directories in your backup procedures to preserve all application state.

For file uploads and attack resources, CipherSwarm uses named Docker volumes (tus_uploads and attack_resources) which are typically mounted to dedicated filesystems in production environments.

Additional Notes#

• For troubleshooting or advanced configuration, refer to the repository's README and Docker Compose files for further details.

Reference: CipherSwarm README and docker-compose.yml
Reference: docker-compose.yml