Skip to content

Feat: Custom start commands #10842

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Meldiron merged 4 commits into from
Nov 24, 2025
Merged

Feat: Custom start commands #10842

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f907f76
Custom start command implementation
Meldiron Nov 19, 2025
7f3c0c9
AI review fixes
Meldiron Nov 19, 2025
856c1d6
Remove functions refference to start command
Meldiron Nov 24, 2025
d99a527
Merge branch 'feat-1.8.x-new-schema' into feat-custom-start-commands
Meldiron Nov 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions app/config/collections/projects.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -765,6 +765,18 @@
'default' => null,
'filters' => [],
],
[
// At the moment, always empty (no runtime supports it yet)
'array' => false,
'$id' => ID::custom('startCommand'),
'type' => Database::VAR_STRING,
'format' => '',
'size' => 16384,
'signed' => true,
'required' => false,
'default' => null,
'filters' => [],
],
[
'array' => false,
'$id' => ID::custom('buildSpecification'),
Expand Down Expand Up @@ -1046,6 +1058,17 @@
'default' => null,
'filters' => [],
],
[
'array' => false,
'$id' => ID::custom('startCommand'),
'type' => Database::VAR_STRING,
'format' => '',
'size' => 16384,
'signed' => true,
'required' => false,
'default' => null,
'filters' => [],
],
[
'$id' => ID::custom('fallbackFile'),
'type' => Database::VAR_STRING,
Expand Down Expand Up @@ -1379,6 +1402,17 @@
'default' => null,
'filters' => [],
],
[
'array' => false,
'$id' => ID::custom('startCommand'),
'type' => Database::VAR_STRING,
'format' => '',
'size' => 16384,
'signed' => true,
'required' => false,
'default' => null,
'filters' => [],
],
[
'array' => false,
'$id' => ID::custom('buildOutput'),
Expand Down
1 change: 1 addition & 0 deletions app/controllers/api/vcs.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -304,6 +304,7 @@
'resourceType' => $resourceCollection,
'entrypoint' => $resource->getAttribute('entrypoint', ''),
'buildCommands' => \implode(' && ', $commands),
'startCommand' => $resource->getAttribute('startCommand', ''),
'buildOutput' => $resource->getAttribute('outputDirectory', ''),
'adapter' => $resource->getAttribute('adapter', ''),
'fallbackFile' => $resource->getAttribute('fallbackFile', ''),
Expand Down
4 changes: 4 additions & 0 deletions app/controllers/general.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -538,6 +538,10 @@ function router(App $utopia, Database $dbForPlatform, callable $getProjectDB, Sw
}
}

if (!empty($deployment->getAttribute('startCommand', ''))) {
$startCommand = 'cd /usr/local/server/src/function/ && ' . $deployment->getAttribute('startCommand', '');
}
Comment thread
Meldiron marked this conversation as resolved.

$runtimeEntrypoint = match ($version) {
'v2' => '',
default => "cp /tmp/code.$extension /mnt/code/code.$extension && nohup helpers/start.sh \"$startCommand\"",
Expand Down
2 changes: 2 additions & 0 deletions src/Appwrite/Platform/Modules/Compute/Base.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,6 +106,7 @@ public function redeployVcsFunction(Request $request, Document $function, Docume
'resourceType' => 'functions',
'entrypoint' => $entrypoint,
'buildCommands' => $function->getAttribute('commands', ''),
'startCommand' => $function->getAttribute('startCommand', ''),
'type' => 'vcs',
'installationId' => $installation->getId(),
'installationInternalId' => $installation->getSequence(),
Expand Down Expand Up @@ -202,6 +203,7 @@ public function redeployVcsSite(Request $request, Document $site, Document $proj
'resourceInternalId' => $site->getSequence(),
'resourceType' => 'sites',
'buildCommands' => implode(' && ', $commands),
'startCommand' => $site->getAttribute('startCommand', ''),
'buildOutput' => $site->getAttribute('outputDirectory', ''),
'adapter' => $site->getAttribute('adapter', ''),
'fallbackFile' => $site->getAttribute('fallbackFile', ''),
Expand Down
2 changes: 2 additions & 0 deletions src/Appwrite/Platform/Modules/Functions/Http/Deployments/Create.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -243,6 +243,7 @@ public function action(
'resourceType' => 'functions',
'entrypoint' => $entrypoint,
'buildCommands' => $commands,
'startCommand' => $function->getAttribute('startCommand', ''),
'sourcePath' => $path,
'sourceSize' => $fileSize,
'totalSize' => $fileSize,
Expand Down Expand Up @@ -280,6 +281,7 @@ public function action(
'resourceType' => 'functions',
'entrypoint' => $entrypoint,
'buildCommands' => $commands,
'startCommand' => $function->getAttribute('startCommand', ''),
'sourcePath' => $path,
'sourceSize' => $fileSize,
'totalSize' => $fileSize,
Expand Down
1 change: 1 addition & 0 deletions src/Appwrite/Platform/Modules/Functions/Http/Deployments/Duplicate/Create.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,7 @@ public function action(
'totalSize' => $deployment->getAttribute('sourceSize', 0),
'entrypoint' => $function->getAttribute('entrypoint'),
'buildCommands' => $function->getAttribute('commands', ''),
'startCommand' => $function->getAttribute('startCommand', ''),
'buildStartedAt' => null,
'buildEndedAt' => null,
'buildDuration' => null,
Expand Down
1 change: 1 addition & 0 deletions src/Appwrite/Platform/Modules/Functions/Http/Deployments/Template/Create.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,7 @@ function: $function,
'resourceType' => 'functions',
'entrypoint' => $function->getAttribute('entrypoint', ''),
'buildCommands' => $function->getAttribute('commands', ''),
'startCommand' => $function->getAttribute('startCommand', ''),
'providerRepositoryName' => $repository,
'providerRepositoryOwner' => $owner,
'providerRepositoryUrl' => $repositoryUrl,
Expand Down
5 changes: 5 additions & 0 deletions src/Appwrite/Platform/Modules/Functions/Http/Executions/Create.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -396,6 +396,11 @@ public function action(
try {
$version = $function->getAttribute('version', 'v2');
$command = $runtime['startCommand'];

if (!empty($deployment->getAttribute('startCommand', ''))) {
$command = 'cd /usr/local/server/src/function/ && ' . $deployment->getAttribute('startCommand', '');
}

$source = $deployment->getAttribute('buildPath', '');
$extension = str_ends_with($source, '.tar') ? 'tar' : 'tar.gz';
$command = $version === 'v2' ? '' : "cp /tmp/code.$extension /mnt/code/code.$extension && nohup helpers/start.sh \"$command\"";
Expand Down
1 change: 1 addition & 0 deletions src/Appwrite/Platform/Modules/Functions/Http/Functions/Create.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -348,6 +348,7 @@ function: $function,
'resourceType' => 'functions',
'entrypoint' => $function->getAttribute('entrypoint', ''),
'buildCommands' => $function->getAttribute('commands', ''),
'startCommand' => $function->getAttribute('startCommand', ''),
Comment thread
Meldiron marked this conversation as resolved.
'type' => 'manual',
'activate' => true,
]));
Expand Down
2 changes: 2 additions & 0 deletions src/Appwrite/Platform/Modules/Sites/Http/Deployments/Create.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -251,6 +251,7 @@ public function action(
'resourceId' => $site->getId(),
'resourceType' => 'sites',
'buildCommands' => \implode(' && ', $commands),
'startCommand' => $site->getAttribute('startCommand', ''),
'buildOutput' => $outputDirectory,
'adapter' => $site->getAttribute('adapter', ''),
'fallbackFile' => $site->getAttribute('fallbackFile', ''),
Expand Down Expand Up @@ -317,6 +318,7 @@ public function action(
'resourceId' => $site->getId(),
'resourceType' => 'sites',
'buildCommands' => \implode(' && ', $commands),
'startCommand' => $site->getAttribute('startCommand', ''),
'buildOutput' => $outputDirectory,
'adapter' => $site->getAttribute('adapter', ''),
'fallbackFile' => $site->getAttribute('fallbackFile', ''),
Expand Down
1 change: 1 addition & 0 deletions src/Appwrite/Platform/Modules/Sites/Http/Deployments/Duplicate/Create.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,7 @@ public function action(
'sourcePath' => $destination,
'totalSize' => $deployment->getAttribute('sourceSize', 0),
'buildCommands' => \implode(' && ', $commands),
'startCommand' => $site->getAttribute('startCommand', ''),
'buildOutput' => $site->getAttribute('outputDirectory', ''),
'adapter' => $site->getAttribute('adapter', ''),
'fallbackFile' => $site->getAttribute('fallbackFile', ''),
Expand Down
1 change: 1 addition & 0 deletions src/Appwrite/Platform/Modules/Sites/Http/Deployments/Template/Create.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,7 @@ public function action(
'resourceInternalId' => $site->getSequence(),
'resourceType' => 'sites',
'buildCommands' => \implode(' && ', $commands),
'startCommand' => $site->getAttribute('startCommand', ''),
'buildOutput' => $site->getAttribute('outputDirectory', ''),
'providerRepositoryName' => $repository,
'providerRepositoryOwner' => $owner,
Expand Down
3 changes: 3 additions & 0 deletions src/Appwrite/Platform/Modules/Sites/Http/Sites/Create.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ public function __construct()
->param('timeout', 30, new Range(1, (int) System::getEnv('_APP_SITES_TIMEOUT', 30)), 'Maximum request time in seconds.', true)
->param('installCommand', '', new Text(8192, 0), 'Install Command.', true)
->param('buildCommand', '', new Text(8192, 0), 'Build Command.', true)
->param('startCommand', '', new Text(8192, 0), 'Custom start command. Leave empty to use default.', true)
->param('outputDirectory', '', new Text(8192, 0), 'Output Directory for site.', true)
->param('buildRuntime', '', new WhiteList(array_keys(Config::getParam('runtimes')), true), 'Runtime to use during build step.')
->param('adapter', '', new WhiteList(['static', 'ssr']), 'Framework adapter defining rendering strategy. Allowed values are: static, ssr', true)
Expand Down Expand Up @@ -107,6 +108,7 @@ public function action(
int $timeout,
string $installCommand,
string $buildCommand,
string $startCommand,
string $outputDirectory,
string $buildRuntime,
string $adapter,
Expand Down Expand Up @@ -157,6 +159,7 @@ public function action(
'timeout' => $timeout,
'installCommand' => $installCommand,
'buildCommand' => $buildCommand,
'startCommand' => $startCommand,
'outputDirectory' => $outputDirectory,
'search' => implode(' ', [$siteId, $name, $framework]),
'fallbackFile' => $fallbackFile,
Expand Down
4 changes: 4 additions & 0 deletions src/Appwrite/Platform/Modules/Sites/Http/Sites/Update.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -73,6 +73,7 @@ public function __construct()
->param('timeout', 30, new Range(1, (int) System::getEnv('_APP_SITES_TIMEOUT', 30)), 'Maximum request time in seconds.', true)
->param('installCommand', '', new Text(8192, 0), 'Install Command.', true)
->param('buildCommand', '', new Text(8192, 0), 'Build Command.', true)
->param('startCommand', '', new Text(8192, 0), 'Custom start command. Leave empty to use default.', true)
Comment thread
Meldiron marked this conversation as resolved.
->param('outputDirectory', '', new Text(8192, 0), 'Output Directory for site.', true)
->param('buildRuntime', '', new WhiteList(array_keys(Config::getParam('runtimes')), true), 'Runtime to use during build step.', true)
->param('adapter', '', new WhiteList(['static', 'ssr']), 'Framework adapter defining rendering strategy. Allowed values are: static, ssr', true)
Expand Down Expand Up @@ -115,6 +116,7 @@ public function action(
int $timeout,
string $installCommand,
string $buildCommand,
string $startCommand,
string $outputDirectory,
string $buildRuntime,
string $adapter,
Expand Down Expand Up @@ -233,6 +235,7 @@ public function action(
$site->getAttribute('name') !== $name ||
$site->getAttribute('buildCommand') !== $buildCommand ||
$site->getAttribute('installCommand') !== $installCommand ||
$site->getAttribute('startCommand') !== $startCommand ||
$site->getAttribute('outputDirectory') !== $outputDirectory ||
$site->getAttribute('providerRootDirectory') !== $providerRootDirectory ||
$site->getAttribute('framework') !== $framework
Expand Down Expand Up @@ -269,6 +272,7 @@ public function action(
'timeout' => $timeout,
'installCommand' => $installCommand,
'buildCommand' => $buildCommand,
'startCommand' => $startCommand,
'outputDirectory' => $outputDirectory,
'installationId' => $installation->getId(),
'installationInternalId' => $installation->getSequence(),
Expand Down
5 changes: 5 additions & 0 deletions src/Appwrite/Platform/Workers/Functions.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -522,6 +522,11 @@ private function execute(
try {
$version = $function->getAttribute('version', 'v2');
$command = $runtime['startCommand'];

if (!empty($deployment->getAttribute('startCommand', ''))) {
$command = 'cd /usr/local/server/src/function/ && ' . $deployment->getAttribute('startCommand', '');
}
Comment thread
Meldiron marked this conversation as resolved.

$source = $deployment->getAttribute('buildPath', '');
$extension = str_ends_with($source, '.tar') ? 'tar' : 'tar.gz';
$command = $version === 'v2' ? '' : "cp /tmp/code.$extension /mnt/code/code.$extension && nohup helpers/start.sh \"$command\"";
Expand Down
6 changes: 6 additions & 0 deletions src/Appwrite/Utopia/Response/Model/Site.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,12 @@ public function __construct()
'default' => '',
'example' => 'npm run build',
])
->addRule('startCommand', [
'type' => self::TYPE_STRING,
'description' => 'Custom command to use when starting site runtime.',
'default' => '',
'example' => 'node custom-server.mjs',
])
->addRule('outputDirectory', [
'type' => self::TYPE_STRING,
'description' => 'The directory where the site build output is located.',
Expand Down
59 changes: 59 additions & 0 deletions tests/e2e/Services/Sites/SitesCustomServerTest.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2967,6 +2967,65 @@ public function testCookieHeader()
$this->cleanupSite($siteId);
}

public function testSiteCustomStartCommand(): void
Comment thread
Meldiron marked this conversation as resolved.
{
$siteId = $this->setupSite([
'siteId' => ID::unique(),
'name' => 'Astro site',
'framework' => 'astro',
'adapter' => 'ssr',
'startCommand' => 'node custom-server.js',
'buildRuntime' => 'node-22',
'outputDirectory' => './dist',
'buildCommand' => 'npm run build',
'installCommand' => 'npm install',
'fallbackFile' => '',
]);

$this->assertNotEmpty($siteId);

$domain = $this->setupSiteDomain($siteId);

$deploymentId = $this->setupDeployment($siteId, [
'code' => $this->packageSite('astro-custom-start-command'),
'activate' => 'true'
]);

$this->assertNotEmpty($deploymentId);

$domain = $this->getSiteDomain($siteId);
$proxyClient = new Client();
$proxyClient->setEndpoint('http://' . $domain);

$response = $proxyClient->call(Client::METHOD_GET, '/');
$this->assertEquals(200, $response['headers']['status-code']);
$this->assertStringContainsString("Homepage OK", $response['body']);

$response = $proxyClient->call(Client::METHOD_GET, '/ssr');
$this->assertEquals(200, $response['headers']['status-code']);
$this->assertStringContainsString("SSR OK", $response['body']);
$originalBody = $response['body'];
$response = $proxyClient->call(Client::METHOD_GET, '/ssr');
$this->assertEquals(200, $response['headers']['status-code']);
$this->assertStringContainsString("SSR OK", $response['body']);
$this->assertNotEquals($originalBody, $response['body']); // Includes Date.now()

$response = $proxyClient->call(Client::METHOD_GET, '/ssr-custom');
$this->assertEquals(200, $response['headers']['status-code']);
$this->assertStringContainsString("Custom SSR OK", $response['body']);
$originalBody = $response['body'];
$response = $proxyClient->call(Client::METHOD_GET, '/ssr-custom');
$this->assertEquals(200, $response['headers']['status-code']);
$this->assertStringContainsString("Custom SSR OK", $response['body']);
$this->assertNotEquals($originalBody, $response['body']); // Includes Date.now()

$response = $proxyClient->call(Client::METHOD_GET, '/non-existing');
$this->assertEquals(500, $response['headers']['status-code']);
$this->assertStringContainsString("Custom error", $response['body']);

$this->cleanupSite($siteId);
}

public function testSiteSpecifications()
{
// Check if the site specifications are correctly set in builds
Expand Down
24 changes: 24 additions & 0 deletions tests/resources/sites/astro-custom-start-command/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
# build output
dist/
# generated types
.astro/

# dependencies
node_modules/

# logs
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*


# environment variables
.env
.env.production

# macOS-specific files
.DS_Store

# jetbrains setting folder
.idea/
10 changes: 10 additions & 0 deletions tests/resources/sites/astro-custom-start-command/astro.config.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
// @ts-check
import { defineConfig } from 'astro/config';
import node from '@astrojs/node';

// https://astro.build/config
export default defineConfig({
adapter: node({
mode: 'middleware',
}),
});
16 changes: 16 additions & 0 deletions tests/resources/sites/astro-custom-start-command/custom-server.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
import express from 'express';
import { handler as ssrHandler } from './server/entry.mjs';

const app = express();
const base = '/';
app.use(base, express.static('client/'));
app.get('/ssr-custom', (_req, res) => {
res.send('Custom SSR OK (' + Date.now() + ')');
});
app.use(ssrHandler);

app.use((_req, res) => {
res.status(500).send('Custom error');
});

app.listen(3000);
Loading