NanokitDocs

Appearance

Persistent Storage with AWS EFS ​

By default, AWS Fargate tasks are stateless. This means any data written to the container's local filesystem is lost when the task restarts or updates.

For stateful services like MongoDB, PostgreSQL, or shared file storage, Nanokit provides automated integration with Amazon EFS (Elastic File System).

How it Works ​

When you define a volume in your nanokit.yml for an AWS environment, Nanokit orchestration performs the following steps:

  1. Provisioning: Creates a project-wide EFS File System (e.g., nk-efs-myapp-stage).
  2. Networking: Sets up Mount Targets in all public subnets of your VPC.
  3. Security: Configures Security Group rules to allow NFS (Port 2049) traffic between the Fargate tasks and the EFS cluster.
  4. Mounting: Automatically registers the EFS volume in the ECS Task Definition and mounts it to the specified path in your container.

Configuration ​

To enable EFS persistence, add a volumes section to your service definition:

yaml
services:
  database:
    image: mongo:latest
    volumes:
      - data-store:/data/db # <volume-name>:<container-path>

Volume Syntax ​

  • Name: A descriptive name for the volume (e.g., data-store). This helps identify the storage in the AWS Console.
  • Path: The internal path in the container where the data should be persisted (e.g., /data/db for MongoDB).

Preparation & Permissions ​

To allow Nanokit to manage EFS for you, ensure your IAM credentials have the following permission:

  • AmazonElasticFileSystemFullAccess

Important. If you are using a restricted IAM policy, ensure you allow elasticfilesystem:CreateFileSystem, elasticfilesystem:CreateMountTarget, and elasticfilesystem:Describe*.

Best Practices ​

Performance ​

EFS is optimized for concurrent access and high availability. For most Nanokit applications, the default General Purpose performance mode with Bursting throughput is the most cost-effective choice and is what Nanokit uses by default.

Managed vs Self-Hosted ​

While EFS allows you to run your own database containers (like MongoDB), for production workloads where high availability and backups are critical, consider pointing your service at a managed offering instead:

  • AWS RDS: for SQL databases (Postgres, MySQL) — see the RDS example.
  • MongoDB Atlas: for MongoDB.

Neon / Turso are not selectable engines

Managed Neon and Turso are planned (roadmap.v3), not shipped — they cannot be set as engine: today. See Databases → Supported Engines.

Use EFS primarily for:

  • Shared assets (uploads, images).
  • Legacy applications requiring a persistent disk.
  • Development/Stage environments where a full RDS instance would be overkill.

Troubleshooting ​

Connectivity ​

If your task fails to start or is stuck in PROVISIONING, check that the Security Group allows inbound traffic on port 2049. Nanokit attempts to configure this automatically, but custom VPC settings might interfere.

Performance Lag ​

EFS is a network-based filesystem. For extremely high-I/O applications (like high-frequency trading or large video rendering), EFS might introduce latency. In such cases, consider using managed services or EBS (on EC2-based ECS).