Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.neptune.dev/llms.txt

Use this file to discover all available pages before exploring further.

Neptune provides access to your application logs and deployment status through your AI assistant.

​
Waiting for Deployment

After deploying, you need to wait for your app to start before it’s accessible. Ask your AI assistant:
“Wait for my deployment to complete”
Don’t skip this step! Your app won’t be accessible until the deployment finishes starting up. Your AI assistant will monitor the status and give you your public IP address when ready (typically 1-2 minutes).

​
Viewing Logs

Ask your AI assistant:
“Show me the logs for my app”
This retrieves recent logs from your running container, including:
  • Application stdout/stderr
  • Startup messages
  • Error traces
  • Request logs (if your app logs them)

​
Checking Deployment Status

Ask your AI assistant:
“What’s the status of my deployment?”
This returns:
  • Infrastructure provisioning status: Ready or provisioning
  • Service running status: Running, Pending, Stopped, or Error
  • Public IP: Your application’s public IP address
  • Resource details: Status of each storage bucket (including bucket ID), secret, and database
Infrastructure: Ready
Service Status: Running
Deployment Revision: 3
Public IP: 52.xxx.xxx.xxxResources:
  • StorageBucket “uploads” - Available (aws_id: bucket-abc123)
  • Secret “STRIPE_API_KEY” - Available
  • Database “my-app-db” - Available

​
Debugging Failed Deployments

If your deployment isn’t working, ask:
“My app isn’t starting. Can you help debug?”
Your AI assistant will:
  1. Check status - Identify if the service is in Error, Stopped, or stuck in Pending
  2. Get logs - Retrieve recent logs to find error messages
  3. Analyze - Identify the likely cause
  4. Suggest fixes - Provide actionable solutions

​
Common Issues

Your application crashed. Check the logs for:
  • Unhandled exceptions
  • Missing configuration or secrets
  • Failed connections to external services
Fix: Review the error, update your code, and redeploy.
The container is starting but not becoming healthy. Common causes:
  • App not listening on the expected port (default: 8080)
  • App taking too long to start
  • Health check failing
Fix: Ensure your app listens on port 8080, or configure port_mappings in neptune.json.
The process exits right after starting. Check for:
  • Missing dependencies
  • Configuration errors
  • Startup script issues
Fix: Run your Docker container locally to debug:
docker build -t myapp .
docker run -p 8080:8080 myapp
Your app expects configuration that isn’t available.Fix: Add secrets to your neptune.json and update your code to fetch them from AWS Secrets Manager:
{
  "kind": "Secret",
  "name": "DATABASE_URL"
}
If you want a managed Postgres database on Neptune, add a Database resource instead:
{
  "kind": "Database",
  "name": "my-app-db"
}
Then ask your AI assistant to provision and update your code.

​
Best Practices

Use structured logging (JSON) for easier debugging:
console.log(JSON.stringify({
  level: 'info',
  message: 'Request processed',
  path: req.path,
  duration: Date.now() - start
}));
Log important information when your app starts:
console.log('Starting server...');
console.log(`Port: ${process.env.PORT || 8080}`);
console.log(`Environment: ${process.env.NODE_ENV}`);
console.log('Server ready');
Log errors with stack traces:
process.on('uncaughtException', (err) => {
  console.error('Uncaught exception:', err.stack);
  process.exit(1);
});