Quick start guide

Get EvoNEST running in just a few minutes with this quick installation guide.

Prerequisites

• Docker Desktop installed and running
• Git installed
• Basic familiarity with command line
• A modern web browser (Chrome, Firefox, Safari, or Edge)

Installation guide

Setting up the development environment

Before deploying EvoNEST to production, it's recommended to test the application in a development environment. This allows you to verify that everything works correctly and to make any necessary adjustments. If you do not want to do this, you can skip to the Production setup section.

1. Clone the repository

git clone https://github.com/daniele-liprandi/EvoNEST-backbone.git
cd EvoNEST-backbone

2. Set up environment files

In this repository, you will find already configured environment files for production and development. You should start by editing them to match your environment. The mandatory step is to set up your NEXTAUTH secret. You can generate it by running the following command:

openssl rand -base64 32

Create a new file called .env.local in your project directory with the following content and your key:

NEXTAUTH_SECRET=your-secret-key

The repository includes a docker-compose.dev.yml file with default MongoDB credentials (root:pass). For security, you should change these credentials.

Optional but recommended: Update the MongoDB credentials in docker-compose.dev.yml:

# Find the mongo_dev service and update:
MONGO_INITDB_ROOT_USERNAME: root
MONGO_INITDB_ROOT_PASSWORD: pass  # Change this to a secure password

Then create a new file called .env.development with matching credentials:

NEXTAUTH_URL=http://localhost:3005
MONGODB_URI=mongodb://root:pass@mongo_dev:27017
STORAGE_PATH='/usr/evonest/file_storage_dev'

Security Note

If you change the MongoDB password in docker-compose.dev.yml, make sure to update it in three places:

1. mongo_dev service: MONGO_INITDB_ROOT_PASSWORD
2. mongo-express service: ME_CONFIG_MONGODB_ADMINPASSWORD and ME_CONFIG_MONGODB_URL
3. .env.development: MONGODB_URI

3. Start the development environment

Make sure that your docker instance is running and execute

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

This will start:

• EvoNEST Application: Available at http://localhost:3005
• MongoDB Database: Running on port 27019 with authentication
• Admin Tools: Mongo Express tool for managing the database, available at http://localhost:8081

4. Access EvoNEST

Open your browser and navigate to http://localhost:3005

Setting up the production environment

If you haven't already, make sure to complete Step 1 and Step 2 before proceeding.

The production setup also uses default credentials (root:pass) that you should change for security.

Optional but recommended: Update the MongoDB credentials in docker-compose.yml:

# Find the mongo service and update:
MONGO_INITDB_ROOT_USERNAME: root
MONGO_INITDB_ROOT_PASSWORD: pass  # Change this to a secure password

Then create the production environment file .env.production with matching credentials:

NEXTAUTH_URL=http://localhost:3000
MONGODB_URI=mongodb://root:pass@mongo:27017
STORAGE_PATH='/usr/evonest/file_storage'

Security Note

If you change the MongoDB password in docker-compose.yml, make sure to update it in two places:

1. mongo service: MONGO_INITDB_ROOT_PASSWORD
2. backup service: MONGO_URI
3. .env.production: MONGODB_URI

To start the production setup, make sure that your docker instance is running and execute

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

This will start:

• Production Server: Available at http://localhost:3000
• MongoDB Database: Running on port 27017 with authentication
• Admin Tools: Mongo Express tool for managing the database, available at http://localhost:8081
• Backup Service: Scheduled backups of the database, making copies of your data every 24 hours for a week, every week for a month, and month for a year.

First login

1. Navigate to the EvoNEST application in your browser
2. Login using the default credentials:
   • Username: admin
   • Password: pass

Note: We strongly advise to set up Nextauth with a secure provider of your choice, compatible with the rules of your institution. EvoNEST leverages NextJS, meaning that you can use any NextAuth provider, such as Google, GitHub, or custom OAuth providers. For more information, refer to the NextAuth documentation.

Verify installation

To ensure everything is working:

1. Check the dashboard: You should see the main EvoNEST interface
2. Test navigation: Click through the main menu items (Samples, Traits, Experiments, Settings)

✅ Installation complete!

Next steps

Now that you have EvoNEST running:

1. Configure your NEST: See the NEST setup guide to configure your laboratory's instance
2. Manage users: Learn about user accounts to add team members
3. Learn the features: Explore the User documentation for:
   • Sample management
   • Data collection
   • Experiments
   • Data analysis
   • Data export

Getting help

If you encounter issues:

• Check the logs: docker compose logs -f
• View container status: docker compose ps
• Troubleshooting: See the Workshop troubleshooting guide
• Report issues: Visit our GitHub repository

For developers

Need to customize EvoNEST?

• Technical documentation - Authentication setup, component development, parsers
• GitHub repository - Report issues and contribute
• Testing: Run tests with npm run test or npm run nxtest