Frequently Asked Questions

This FAQ covers the most common questions about nself. If you don't find your answer here, check our troubleshooting guide or get support.

Getting Started

What is nself?

nself is a comprehensive backend-as-a-service (BaaS) platform that provides everything you need to build modern applications: PostgreSQL database, GraphQL API via Hasura, Redis caching, MinIO storage, and support for custom microservices in NestJS, Python, and Go.

What makes nself different from other BaaS platforms?

Unlike cloud-based services, nself runs entirely on your infrastructure giving you:

Complete Control: Your data stays on your servers
No Vendor Lock-in: Everything is standard Docker containers
Cost Effective: No per-request pricing or usage limits
Customizable: Full access to modify any component
Privacy Compliant: Perfect for GDPR, HIPAA, and other regulations

What are the system requirements?

Minimum requirements:

OS: Linux, macOS, or Windows with WSL2
CPU: 2 cores (4 cores recommended)
RAM: 4GB (8GB recommended)
Storage: 10GB free space (SSD recommended)
Docker: Version 20.10+ with Docker Compose

How much does nself cost?

nself is completely free and open source. You only pay for your server infrastructure. There are no licensing fees, usage limits, or subscription costs.

Installation and Setup

How do I install nself?

# One-line installation
curl -fsSL nself.org/install.sh | bash

# Or manual installation
wget https://github.com/acamarata/nself/releases/latest/download/nself-linux-amd64.tar.gz
tar -xzf nself-linux-amd64.tar.gz
sudo mv nself /usr/local/bin/

Can I install nself without Docker?

No, nself requires Docker as it's built around containerized services. Docker provides isolation, consistency, and easy deployment. However, Docker is automatically installed if not present on most systems.

Can I run nself in production?

Yes! nself is designed for production use. Use nself prod to generate production-ready configuration with security hardening, SSL/TLS, monitoring, and backup automation.

How do I update nself?

# Update to latest version
nself update

# Update to specific version
nself update --version v0.3.0

# Check current version
nself version

Configuration and Customization

How do I customize the default configuration?

Edit your .env.local file to customize any aspect of your deployment:

# Edit configuration
nano .env.local

# Rebuild with new configuration
nself build && nself restart

Can I use my own custom domain?

Yes! Configure your domain in the environment file:

# For production
DOMAIN=myapp.com
SSL_MODE=letsencrypt
LETSENCRYPT_EMAIL=admin@myapp.com

# Rebuild configuration
nself build && nself restart

How do I add custom microservices?

nself supports custom microservices in multiple languages:

# Enable NestJS services
NESTJS_SERVICES=api,webhooks,auth-service

# Enable Python services  
PYTHON_SERVICES=ml-processor,data-api

# Enable Go services
GOLANG_SERVICES=websocket-server,gateway

# Enable background workers
BULLMQ_WORKERS=email-worker,notification-worker

Can I disable services I don't need?

Yes, you can disable any optional services:

# Disable optional services
REDIS_ENABLED=false
MINIO_ENABLED=false
NHOST_DASHBOARD_ENABLED=false
MAILHOG_ENABLED=false

# Core services (PostgreSQL, Hasura) cannot be disabled

Database and Data Management

How do I manage my database schema?

nself uses DBML (Database Markup Language) for schema management:

# Edit your schema
nano schema.dbml

# Generate and apply migrations
nself db run

# Check migration status
nself db status

How do I backup my database?

# Manual backup
nself db backup

# Named backup
nself db backup --name "before-migration"

# Automated daily backups (in production config)
BACKUP_ENABLED=true
BACKUP_SCHEDULE=0 2 * * *  # Daily at 2 AM

Can I connect to my database with external tools?

Yes, the PostgreSQL database is accessible on port 5432:

# Connection details
Host: localhost (or your server IP)
Port: 5432
Database: [your database name]
Username: postgres
Password: [your postgres password]

# Command line access
nself exec postgres psql -U postgres

How do I seed my database with initial data?

# Create seed files in seeds/ directory
mkdir seeds
echo "INSERT INTO users (email, name) VALUES ('admin@example.com', 'Admin');" > seeds/001_initial_users.sql

# Run seeding
nself db seed

GraphQL and API

How do I access the GraphQL API?

Your GraphQL API is automatically available once nself starts:

API Endpoint: http://localhost:8080/v1/graphql
Console: http://localhost:8080/console
GraphiQL: Built into the Hasura console

How do I add authentication to my GraphQL API?

Hasura uses JWT tokens for authentication. Configure JWT settings:

# In .env.local
HASURA_GRAPHQL_JWT_SECRET={"type":"HS256","key":"your-jwt-secret-key"}

# Your JWT tokens need these claims:
{
  "sub": "user-id",
  "https://hasura.io/jwt/claims": {
    "x-hasura-allowed-roles": ["user", "admin"],
    "x-hasura-default-role": "user",
    "x-hasura-user-id": "user-id"
  }
}

Can I add custom business logic to my API?

Yes, using Hasura Actions or custom microservices:

Actions: Add custom endpoints that Hasura calls
Remote Schemas: Integrate external GraphQL APIs
Event Triggers: React to database changes
Microservices: Add NestJS, Python, or Go services

Development Workflow

How do I develop with hot reloading?

Development mode includes automatic reloading:

# Enable development features
AUTO_RELOAD=true
WATCH_FILES=true

# nself will automatically restart services when code changes

Can I use nself with my frontend framework?

Yes! nself works with any frontend framework. Popular combinations:

Next.js: Use Apollo Client or urql for GraphQL
React: Use Apollo Client, Relay, or urql
Vue.js: Use Apollo Client or graphql-request
Angular: Use Apollo Angular
Svelte: Use graphql-request or Apollo

How do I manage different environments?

# Development
nself init  # Creates .env.local

# Staging
nself config generate --env staging
# Edit .env.staging, then:
nself up --env staging

# Production
nself prod  # Creates .env.prod-template (copy to .env before deployment)
nself up --env production

Deployment and Production

How do I deploy nself to a production server?

# 1. Generate production configuration
nself prod --domain myapp.com --ssl

# 2. Copy to server
rsync -av . server:/opt/myapp/ --exclude node_modules

# 3. Deploy on server
ssh server "cd /opt/myapp && nself up -d"

# 4. Check status
ssh server "cd /opt/myapp && nself status"

Can I use nself with Kubernetes?

While nself is designed for Docker Compose, you can export the configuration to Kubernetes:

# Convert Docker Compose to Kubernetes manifests
kompose convert -f docker-compose.yml

# Or use Helm charts (coming soon)
nself export --format helm

How do I set up SSL/HTTPS?

# Automatic SSL with Let's Encrypt
SSL_MODE=letsencrypt
LETSENCRYPT_EMAIL=admin@myapp.com
DOMAIN=myapp.com

# Or provide your own certificates
SSL_MODE=custom
SSL_CERT_PATH=/path/to/cert.pem
SSL_KEY_PATH=/path/to/key.pem

How do I scale my nself deployment?

# Scale specific services
NESTJS_API_REPLICAS=3
BULLMQ_WORKER_REPLICAS=2
HASURA_REPLICAS=2

# Configure resource limits
POSTGRES_MEMORY_LIMIT=2048MB
POSTGRES_CPU_LIMIT=2.0
HASURA_MEMORY_LIMIT=1024MB

Storage and Files

How do I handle file uploads?

nself includes MinIO for S3-compatible object storage:

# MinIO is accessible at:
API: http://localhost:9000
Console: http://localhost:9001

# Use any S3 SDK to upload files
# Default credentials: minioadmin / minioadmin

Can I use external storage providers?

Yes, you can configure external storage:

# Disable MinIO and use external S3
MINIO_ENABLED=false
AWS_S3_BUCKET=my-bucket
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret

# Or use other S3-compatible services like DigitalOcean Spaces

Performance and Optimization

How can I optimize nself performance?

Database: Add indexes, tune PostgreSQL settings
Caching: Enable Redis caching for frequently accessed data
Resources: Allocate appropriate CPU/memory limits
CDN: Use a CDN for static assets
Monitoring: Set up monitoring to identify bottlenecks

How do I monitor my nself deployment?

# Built-in monitoring
nself status --resources
nself health --verbose

# Enable metrics collection
METRICS_ENABLED=true
PROMETHEUS_ENABLED=true
GRAFANA_ENABLED=true

# Check logs
nself logs --tail 100

Security

Is nself secure by default?

nself includes security best practices:

Default Passwords: Changed during initialization
Network Isolation: Services communicate over private networks
HTTPS: SSL/TLS encryption in production
JWT Authentication: Secure API access
Regular Updates: Keep all components updated

How do I secure my nself deployment?

Change Default Passwords: Use strong, unique passwords
Enable HTTPS: Use SSL certificates for all endpoints
Firewall Rules: Only expose necessary ports
Regular Backups: Automated backup strategy
Keep Updated: Regular security updates

Troubleshooting

Services won't start, what should I do?

# Check what's wrong
nself doctor
nself status --verbose
nself logs

# Common fixes
nself down && nself up
nself restart
nself reset --soft  # Preserves data

I'm getting port conflicts, how do I fix them?

# Find what's using the port
sudo netstat -tulpn | grep :5432

# Kill the process or change ports
nself config set POSTGRES_PORT 5433
nself config set HASURA_PORT 8081
nself build && nself up

My database data disappeared, what happened?

Data loss usually happens when Docker volumes are removed. To prevent this:

Don't use nself down --volumes unless you want to delete data
Regular backups: nself db backup
Check volumes: docker volume ls
Restore from backup: nself db restore

Migration and Compatibility

Can I migrate from other BaaS platforms?

Yes, nself provides migration tools for popular platforms:

Firebase: Export Firestore data and import to PostgreSQL
Supabase: Direct PostgreSQL migration
Hasura Cloud: Export metadata and migrations
AWS Amplify: Schema and data migration tools

Is nself compatible with existing PostgreSQL databases?

Yes, you can connect nself to existing PostgreSQL databases:

# Use external PostgreSQL
POSTGRES_EXTERNAL=true
POSTGRES_HOST=your-db-server.com
POSTGRES_PORT=5432
POSTGRES_DB=existing_database
POSTGRES_USER=existing_user
POSTGRES_PASSWORD=existing_password

Licensing and Support

What license is nself released under?

nself is released under the MIT License, making it free to use for personal and commercial projects without restrictions.

Where can I get help if I'm stuck?

Documentation: Comprehensive guides at docs.nself.org
GitHub Issues: Bug reports and feature requests
GitHub Discussions: Community Q&A and discussions
Examples: Real-world examples in the repository

Can I get commercial support for nself?

Professional support, consulting, and custom development services are available. Contact us for enterprise support options.

Didn't find your answer?

Check our troubleshooting guide for technical issues, or get support from the community and maintainers.

Next Steps

Now that you have answers to common questions:

Quick Start Guide - Get started with nself
Troubleshooting - Solve technical issues
Architecture - Understand how nself works
Support - Get help from the community

These FAQs cover the most common questions. The nself community is always ready to help with specific questions or unique use cases.