Deploying and Invoking a Node.js Function in Appwrite: A Practical Guide

What You’ll Achieve

By the end of this article you will have a fully‑deployed Node.js function in Appwrite, be able to invoke it via HTTP or SDK, and know how to verify its health and recover from common deployment hiccups.

Prerequisites

• Appwrite instance running (self‑hosted or Appwrite Cloud) with an active project.
• Appwrite CLI installed and authenticated: appwrite login (or appwrite init for local dev).
• Node.js 18+ installed locally for writing the function code.
• Docker installed if you prefer a custom runtime image.
• Network access to the Appwrite API endpoint (e.g., https://appwrite.example.com/v1).

Define the Function

Functions are created from a Dockerfile or an Appwrite‑provided runtime image. For a standard Node.js 18 function, the simplest Dockerfile looks like this:

# Dockerfile
FROM node:18-alpine
WORKDIR /usr/src/app
COPY package.json .
RUN npm ci
COPY . .
CMD ["node", "index.js"]

Place index.js next to the Dockerfile. A minimal echo handler could be:

const { Appwrite } = require("appwrite");
const appwrite = new Appwrite();
appwrite.setEndpoint(process.env.APPWRITE_ENDPOINT).setProject(process.env.APPWRITE_PROJECT);

module.exports = async (req, res) => {
  const payload = req.body || {};
  res.json({ received: payload });
};

In a real function you might import the Appwrite SDK to interact with databases or storage.

Create the Function via CLI

Run the following in the directory containing your Dockerfile:

# Create a function resource
appwrite functions create \
  --name "Echo Function" \
  --runtime "node18" \
  --entrypoint "index.js" \
  --timeout 30 \
  --enabled true \
  --environment "APPWRITE_ENDPOINT=https://appwrite.example.com/v1" \
  --environment "APPWRITE_PROJECT=YOUR_PROJECT_ID"

Replace YOUR_PROJECT_ID with the UUID of your project. The CLI will output a JSON object containing the new functionId and status. Verify creation with:

appwrite functions list

Deploy the Function

After creation, the function must be built and deployed. The CLI handles this in one step:

appwrite functions deploy <functionId>

During deployment you’ll see a log stream in the terminal. A successful deployment ends with status: "running". If you used a custom Dockerfile, ensure the image builds locally before pushing; use docker build . to catch syntax errors early.

Invoke the Function

There are two common invocation methods:

• HTTP POST – send a JSON payload to the public URL.
• SDK call – use functions.createExecution from any Appwrite SDK.

HTTP POST Example

Appwrite exposes a public endpoint that looks like:

POST https://appwrite.example.com/v1/functions/<functionId>/executions

Send a request with the Content-Type: application/json header and a body:

curl -X POST \
  https://appwrite.example.com/v1/functions/<functionId>/executions \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello"}'

The response will contain the function’s output and status code. Verify the JSON contains the echoed message.

SDK Invocation

Using the Node.js SDK:

const sdk = require("appwrite");
const client = new sdk.Client();
client.setEndpoint("https://appwrite.example.com/v1");
client.setProject("YOUR_PROJECT_ID");

const functions = new sdk.Functions(client);
const result = await functions.createExecution(
  "<functionId>",
  { message: "Hello" }
);
console.log(result);

Check Function Health

1. Status: appwrite functions get <functionId> should return status: "running".
2. Logs: appwrite functions logs <functionId> streams real‑time logs. Look for INFO entries and absence of ERROR.
3. Invocation Response: The HTTP POST or SDK call should return status: 200 and the expected JSON payload.
4. Timeout: If your function stalls, the log will show a timeout error. Increase the --timeout flag during creation or redeploy with a higher value.

Common Pitfalls & Recovery

• Runtime Mismatch – If you target Node.js 18 but the Docker image is older, the container fails to start. Verify the image tag in the Dockerfile or use --runtime node18 when creating the function.
• Large Payloads – Exceeding the 10 MB limit for HTTP requests will cause a 413 error. Split payloads or use Appwrite storage to transfer large files.
• Permission Errors – The function cannot access Appwrite resources unless the Appwrite SDK is installed and the function’s role has the necessary permissions. Add the SDK via npm install appwrite and grant the role functions:read in the project settings.
• Missing Environment Variables – If you reference process.env.SECRET_KEY but never set it, the function will throw. Use Appwrite Secrets: appwrite secrets create <functionId> SECRET_KEY=actual_value and reference via process.env.SECRET_KEY.
• Deployment Failure – A failed build stops the function. Re‑run appwrite functions deploy <functionId> after correcting the Dockerfile or code.

Practical Recovery Example

Suppose you accidentally push a syntax error. The function logs will show a stack trace. Redeploy with a corrected file:

# Edit index.js to fix the error
appwrite functions deploy <functionId>
# Verify status
appwrite functions get <functionId>
# Check logs for success
appwrite functions logs <functionId>

Limitations & Notes

• Functions run in isolated containers; they cannot directly read Appwrite database tables unless you include the SDK and set proper permissions.
• Container size is limited to 512 MiB. Heavy dependencies can exceed this; consider using a slimmer base image.
• Functions are stateless. Persist data via Appwrite storage or external services.
• Logs are retained for 30 days. If you need long‑term retention, forward logs to an external system (e.g., ELK stack).

Conclusion

Deploying a Node.js function in Appwrite is straightforward once you understand the CLI workflow. Keep the Dockerfile lean, set environment variables securely, and use the built‑in logs for quick debugging. With these steps, you can add custom business logic to your Appwrite project without managing your own server infrastructure.