Frequently Asked Questions (FAQ)
Common questions and answers about working with ServerlessInsight.
Table of Contents
- Installation & Configuration
- Deployment
- Local Development
- Resource Management
- Security & Permissions
- Troubleshooting
- Best Practices
- Other Questions
Installation & Configuration
Q: The CLI installation fails. What should I do?
A: Try these steps:
Check your Node.js version
bashnode --version # Requires >= 22.12Clear the npm cache
bashnpm cache clean --forceUse a mirror registry (useful if you're behind a corporate firewall or in a region with slow npm access)
bashnpm config set registry https://registry.npmmirror.com npm install -g @geek-fun/serverlessinsightVerify network connectivity
bashping registry.npmjs.org
Q: How do I upgrade the CLI?
A: Run the update command:
npm update -g @geek-fun/serverlessinsightOr force a fresh install of the latest version:
npm install -g @geek-fun/serverlessinsight@latestQ: Where should the configuration file go?
A: By default, ServerlessInsight looks for serverlessinsight.yml in the current working directory. You can also:
- Pass
-fto specify a different path - Set the
SI_CONFIG_FILEenvironment variable
# Specify a config file
si deploy -f config/prod.yml
# Use an environment variable
export SI_CONFIG_FILE="config/prod.yml"
si deployQ: How do I manage configurations across multiple projects?
A: A few approaches:
Per-environment config files
project/ ├── serverlessinsight.dev.yml ├── serverlessinsight.prod.yml └── ...Git submodules or package manager workspaces for shared configs
Environment variables to differentiate projects
Deployment
Q: I get a "permission denied" error during deployment.
A: This usually means your cloud provider credentials are misconfigured or lack the required permissions:
Check your environment variables
bashecho $ALIYUN_ACCESS_KEY_ID echo $ALIYUN_ACCESS_KEY_SECRETVerify IAM/RAM user permissions Make sure the user has the right policies attached. For Aliyun, common ones include:
AliyunFCFullAccess: full access to Function ComputeAliyunAPIGatewayFullAccess: full access to API Gateway- Any other policies for services you're using
Use temporary credentials if available
bashexport ALIYUN_SECURITY_TOKEN="your-temporary-token"
Q: How do I recover after a failed deployment?
A: ServerlessInsight preserves any resources that deployed successfully before the failure. To recover:
- Fix the issue in your config or code
- Re-deploy: ServerlessInsight picks up where it left off and continues deploying the remaining resources
If you need to start fresh instead:
Roll back your config with Git
bashgit checkout HEAD~1 serverlessinsight.yml si deploy --stage devOr destroy everything and redeploy
bashsi destroy --stage dev
Q: How do I deploy to a different region?
A: Two options:
Change
provider.regionin your config —provider.regiondecides where every resource lands; changing it and redeploying targets the new region (resources already deployed to the old region stay there and needsi destroywith the old config or manual cleanup).Override from the command line (highest precedence:
-r>SI_REGION>ALIYUN_REGION>provider.region):bashsi deploy --region cn-beijing
Q: Deployment is taking forever. What can I do?
A: Common causes and fixes:
- Large code bundle: trim unnecessary dependencies and use multi-stage builds to reduce package size
- Slow network: check your connection, or use a network closer to the target region
- Slow resource creation: some resources (databases, search services) take time to provision. Check the cloud provider's console to confirm progress
Q: Can I deploy multiple services at once?
A: Not directly, but you can script it:
One config file describes one service (app + service). To deploy several services, keep one config per service (in its own directory) and deploy each in turn:
#!/bin/bash
cd services/api && si deploy --stage dev
cd ../worker && si deploy --stage dev
cd ../web && si deploy --stage devLocal Development
Q: The local server says the port is already in use.
A: The local server listens on 4567 by default. Either free the port, or point si local at another port with SI_LOCALSTACK_SERVER_PORT:
lsof -i :4567
kill -9 <PID>
# or use another port
SI_LOCALSTACK_SERVER_PORT=4568 si local --stage devQ: How do I debug locally?
A: Start with debug mode enabled:
si local --stage dev --debugThen attach your IDE's debugger. For VS Code, add this to .vscode/launch.json:
{
"type": "node",
"request": "attach",
"name": "Attach to ServerlessInsight",
"port": 9229,
"restart": true
}You can also add a debugger statement in your handler:
export async function handler(event: any) {
debugger; // breakpoint
// your code
}Q: File watching isn't working.
A: Try these:
Enable watch mode explicitly
bashsi local --stage dev --watchMake sure you're editing files in the right directory: only changes under
src/are picked up. Re-package your code if neededRestart the local environment
bash# Ctrl+C to stop, then si local --stage dev
Q: Local behavior doesn't match production.
A: A few things to check:
- Environment variables: make sure the same vars are set locally. Use a
.envfile to keep things consistent - Dependency versions: verify
package.jsonmatches what's deployed. Usepackage-lock.jsonto lock versions - Stage config: confirm you're using the same stage for local dev and deployment
Resource Management
Q: How do I see what resources are deployed?
A: A few ways:
- Cloud provider console: log in and look up resources by stack name
- Resource tags: filter by the tags defined in your config, like
owner=geek-fun - Provider CLIbash
# Aliyun example aliyun fc list services aliyun apigateway DescribeApis
Q: How do I update a deployed function's code?
A: Repackage and redeploy:
# After making code changes, rebuild your package, then:
si deploy --stage devServerlessInsight detects code changes and updates the function accordingly.
Q: Can I delete a single resource without tearing down the whole stack?
A: Not directly. The recommended approach:
- Remove the resource from your config file
- Redeploy: ServerlessInsight deletes resources that are no longer in the config
- Or delete manually through the cloud provider's console
⚠️ Always double-check what you're removing before redeploying.
Q: I've hit the resource limit for my cloud account.
A: Cloud providers cap how many of each resource type you can create:
Clean up unused resources
bashsi destroy --stage devRequest a quota increase from your cloud provider: explain your use case and expected usage
Optimize resource usage: merge similar functions, right-size allocations
Security & Permissions
Q: How do I manage secrets and sensitive config values?
A: Best practices:
Use environment variables
bashexport DB_PASSWORD="your-password"Reference them in your config
yamlfunctions: my_function: environment: DB_PASSWORD: ${vars.db_password}Use a secrets manager: Aliyun KMS, Tencent Cloud KMS, HashiCorp Vault, etc.
Never commit secrets to Git
bash# .gitignore .env *.key *.pem
Q: How do I configure VPC and security groups?
A: Add network settings to your function config:
functions:
my_function:
network:
vpc_id: vpc-my-vpc
subnet_ids:
- vsw-subnet1
security_group:
name: my-sg
ingress:
- TCP:0.0.0.0/0:443
egress:
- ALL:0.0.0.0/0:ALLQ: How do I enable function logging?
A: Set log: true in your function config:
functions:
my_function:
log: true⚠️ Note: On Aliyun, SLS log stores take a minute or two to provision. If it's your first deploy, leave logging off, wait a couple of minutes, then redeploy with logging enabled.
Troubleshooting
Q: How do I get more detailed logs?
A: Enable debug mode:
export DEBUG=true
si deploy --stage devAll commands log to stderr, and --json result data goes to stdout. The --debug option exists on si local only.
Q: Deployment is stuck and not progressing.
A: Possible causes:
- Network timeout: check your connection and try again
- Cloud API rate limiting: wait a few minutes and retry, or request a higher limit from your provider
- Resource still provisioning: some resources (databases, search services) take time. Check the cloud provider's console to confirm what's happening
Q: My function times out during execution.
A: Try these:
Increase the timeout
yamlfunctions: my_function: timeout: 60 # secondsOptimize performance: cut unnecessary computation, use async processing, optimize database queries
Split the function: break a large function into smaller ones and chain them together
Q: I'm getting memory errors.
A:
Allocate more memory
yamlfunctions: my_function: memory: 1024 # MBOptimize your code: reduce memory usage, use streaming for large data, release resources when done
Best Practices
Q: How should I organize configs for a large project?
A: A clean structure looks like this:
project/
├── serverlessinsight.yml # main config
├── serverlessinsight.dev.yml # dev overrides
├── serverlessinsight.prod.yml # prod overrides
├── functions/
│ ├── user-service/
│ ├── order-service/
│ └── ...
└── scripts/
└── deploy-all.shQ: How do I manage multiple environments?
A: Use stages in your config:
Each stage holds plain scalar values that you reference via ${stages.<key>} — they are variables, not behavioral switches:
stages:
dev:
memory: 512
test:
memory: 1024
prod:
memory: 2048functions:
api_fn:
memory: ${stages.memory}Deploy to a specific environment with si deploy --stage dev; the region comes from provider.region (or -r), not from a stage key.
Q: How do I keep serverless costs down?
A:
- Right-size your functions: don't over-provision memory or timeout values
- Tune the elastic CU range of Serverless databases: a lower
cu.minkeeps idle cost near zero; right-sizecu.maxinstead of over-provisioning - Monitor spending: use your cloud provider's cost analysis tools to find expensive functions
- Optimize code: shorter cold starts and faster execution mean less billed compute time
Q: How do I ensure high availability?
A:
Deploy the same config to multiple regions by overriding
-r/provider.regionper deployment (keep one state per stage+region combination)Set up health checks on your functions and endpoints
Use load balancing to distribute traffic
Implement failover so traffic reroutes if one region goes down
Other Questions
Q: Is ServerlessInsight free?
A: Yes. ServerlessInsight is open source under the Apache 2.0 license. Free to use, free to modify.
Q: How do I contribute or report a bug?
A:
- Report a bug: GitHub Issues
- Submit code: GitHub Pull Requests
- Email support: support@wentsen.com
Q: Is there a community?
A:
- GitHub Discussions: discussions
Q: How do I get technical support?
A:
Community support (free)
- GitHub Issues
- GitHub Discussions
Commercial support
- Email: support@wentsen.com
- Custom development and consulting available
Didn't find your answer?
If this page doesn't cover your question:
- Search GitHub Issues for similar problems
- Ask on GitHub Discussions
- Email support@wentsen.com
This document is continuously updated. Contributions of questions and answers are welcome.