feat: use a setting for no service projets

Author: Shawiizz

cli/src/commands/app/rollback.ts

@@ -5,7 +5,7 @@
  */
 
 import type { Command } from 'commander';
-import { getPerformer, getComposePath } from '../../utils/config';
+import { getPerformer } from '../../utils/config';
 import { createSpinner } from '../../utils/output';
 import { validateEnv } from '../../utils/validation';
 import { createStackBackend } from '../../services/orchestrator/factory';
@@ -25,9 +25,9 @@ export function registerRollbackCommand(program: Command): void {
     .action(withErrorHandler(async (env: string, service: string | undefined, options: { server?: string }) => {
       const { config, stackName, connection } = validateEnv(env, options.server);
 
-      if (!getComposePath()) {
+      if (config.no_services) {
         throw new DeployError(
-          'Rollback is not supported for upload-only projects (no docker-compose.yml)',
+          'Rollback is not supported for upload-only projects',
           ErrorCode.ROLLBACK_FAILED,
           'To restore a previous version, re-deploy from the corresponding git commit.',
         );

cli/src/commands/deploy-phases.ts

@@ -231,9 +231,14 @@ export async function uploadFiles(ctx: DeployContext): Promise<UploadRollbackPla
       const fileContent = readFileSync(srcAbs);
 
       // Ensure destination and backup dirs exist on all hosts in one call each
-      await Promise.all(plan.hosts.map(({ conn }) =>
-        sshExec(conn, `mkdir -p '${dirname(destPath)}' '${dirname(backupPath)}'`),
-      ));
+      await Promise.all(plan.hosts.map(async ({ name, conn }) => {
+        const r = await sshExec(conn, `mkdir -p '${dirname(destPath)}' '${dirname(backupPath)}'`);
+        if (r.exitCode !== 0) throw new DeployError(
+          `upload: cannot create ${dirname(destPath)} on ${name}: ${r.stderr.trim() || `exit ${r.exitCode}`}`,
+          ErrorCode.DEPLOY_FAILED,
+          `The deploy user must own the destination directory. Run once on the server as root:\n  mkdir -p '${dirname(destPath)}' && chown ${conn.user}: '${dirname(destPath)}'`,
+        );
+      }));
 
       const tasks = plan.hosts.map(hostState => async () => {
         const { name, conn } = hostState;
@@ -253,22 +258,28 @@ export async function uploadFiles(ctx: DeployContext): Promise<UploadRollbackPla
         if (result.exitCode !== 0) {
           const detail = result.stderr.trim() || result.stdout.trim() || `exit code ${result.exitCode}`;
           throw new DeployError(
-            `upload: failed to transfer ${upload.src} to ${name}: ${detail}`,
+            `upload: failed to transfer ${upload.src} → ${destPath} on ${name}: ${detail}`,
             ErrorCode.DEPLOY_FAILED,
             `Ensure ${conn.user} has write access to ${dirname(destPath)} on ${name}. Run once as root:\n  mkdir -p '${dirname(destPath)}' && chown ${conn.user}: '${dirname(destPath)}'`,
           );
         }
 
         if (upload.permissions) {
           const r = await sshExec(conn, `chmod ${upload.permissions} '${destPath}'`);
-          if (r.exitCode !== 0) throw new DeployError(`upload: chmod failed on ${destPath} (${name})`, ErrorCode.DEPLOY_FAILED);
+          if (r.exitCode !== 0) throw new DeployError(
+            `upload: chmod ${upload.permissions} failed on ${destPath} (${name}): ${r.stderr.trim() || `exit ${r.exitCode}`}`,
+            ErrorCode.DEPLOY_FAILED,
+          );
         }
         if (upload.owner) {
           const r = await sshExec(conn, `chown ${upload.owner} '${destPath}'`);
           if (r.exitCode !== 0) throw new DeployError(
-            `upload: chown failed on ${destPath} (${name})`,
+            `upload: chown ${upload.owner} failed on ${destPath} (${name}): ${r.stderr.trim() || `exit ${r.exitCode}`}`,
             ErrorCode.DEPLOY_FAILED,
-            `Grant chown rights:\n  echo '${conn.user} ALL=(ALL) NOPASSWD: /bin/chown * ${dirname(destPath)}/*' >> /etc/sudoers.d/dockflow`,
+            `The deploy user needs sudo rights for chown. Either run once on the server as root:\n` +
+            `  chown ${upload.owner} '${destPath}'\n` +
+            `Or grant the deploy user the right permanently:\n` +
+            `  echo '${conn.user} ALL=(ALL) NOPASSWD: /bin/chown * ${dirname(destPath)}/*' >> /etc/sudoers.d/dockflow`,
           );
         }
       });

cli/src/commands/deploy.ts

@@ -220,11 +220,12 @@ async function resolveSetup(rawEnv: string | undefined, rawVersion: string | und
   const { rendered, composeContent, composeDirPath } = Compose.renderAndResolveCompose(
     { env, version: deployVersion, branch: branchName, project_name: config.project_name, config },
     templateContext,
+    { uploadOnly: config.no_services },
   );
   config = loadConfig({ content: rendered.get('.dockflow/config.yml'), silent: true }) ?? config;
 
-  // Validate --only service names before acquiring the lock
-  if (options.only) {
+  // Validate --only service names before acquiring the lock (skip for no_services — no Docker services)
+  if (options.only && !config.no_services) {
     const compose = Compose.loadFromString(composeContent);
     const available = Object.keys(compose.services);
     const filterSet = options.only.split(',').map((s) => s.trim());

cli/src/schemas/config.schema.ts

@@ -395,4 +395,10 @@ export const DockflowConfigSchema = z.object({
     'Files or directories to transfer to the remote server before deploying. ' +
     'Useful for config files referenced as bind mounts in docker-compose volumes.'
   ),
+
+  no_services: z.boolean().optional().describe(
+    'Set to true for projects with no Docker services (upload-only deployments). ' +
+    'Skips Docker build, compose deploy, and all service commands. ' +
+    'Without this flag, a missing docker-compose.yml is treated as a configuration error.'
+  ),
 });

cli/src/services/compose.ts

@@ -262,6 +262,7 @@ export function renderTemplates(
 export function renderAndResolveCompose(
   ctx: ComposeRenderContext,
   templateContext?: TemplateContext | null,
+  options: { uploadOnly?: boolean } = {},
 ): RenderedComposeResult {
   const projectRoot = getProjectRoot();
 
@@ -275,13 +276,18 @@ export function renderAndResolveCompose(
 
   const originalComposePath = getComposePath();
   if (!originalComposePath) {
-    printWarning('No docker-compose.yml found — skipping Docker build and deploy. Expected at .dockflow/docker/docker-compose.yml');
-    return {
-      rendered,
-      composeContent: 'services: {}\n',
-      composeDirPath: join(projectRoot, '.dockflow', 'docker'),
-      projectRoot,
-    };
+    if (options.uploadOnly) {
+      return {
+        rendered,
+        composeContent: 'services: {}\n',
+        composeDirPath: join(projectRoot, '.dockflow', 'docker'),
+        projectRoot,
+      };
+    }
+    throw new ConfigError(
+      'No docker-compose.yml found',
+      'Expected at docker-compose.yml or .dockflow/docker/docker-compose.yml',
+    );
   }
 
   const composeRelPath = relative(projectRoot, originalComposePath).replace(/\\/g, '/');

cli/src/utils/config.ts

@@ -161,6 +161,7 @@ export interface DockflowConfig {
   proxy?: ProxyConfig;
   notifications?: NotificationsConfig;
   upload?: UploadItem[];
+  no_services?: boolean;
 }
 
 /**

cli/src/utils/errors.ts

@@ -8,7 +8,7 @@
 
 import { printBlank, colors } from './output';
 import { closeAllConnections } from './ssh';
-import { getComposePath } from './config';
+import { loadConfig } from './config';
 
 /**
  * CLI Error codes for different failure scenarios
@@ -208,16 +208,16 @@ export function withErrorHandler<T extends unknown[]>(
   };
 }
 
-/** Wraps withErrorHandler and blocks execution when no docker-compose.yml is found. */
+/** Wraps withErrorHandler and blocks execution when the project is configured as no_services. */
 export function withServicesRequired<T extends unknown[]>(
   action: CommandAction<T>
 ): CommandAction<T> {
   return withErrorHandler(async (...args: T): Promise<void> => {
-    if (!getComposePath()) {
+    if (loadConfig()?.no_services) {
       throw new DeployError(
-        'This command requires Docker services (no docker-compose.yml found)',
+        'This command requires Docker services',
         ErrorCode.VALIDATION_FAILED,
-        'This project has no Docker services configured.',
+        'This project is configured as no_services and has no Docker services.',
       );
     }
     await action(...args);

docs/app/configuration/upload/page.mdx

@@ -32,6 +32,8 @@ services:
 | `service` | `string \| string[]` | Service(s) this upload belongs to. When deploying with `--only`, only uploads matching a targeted service are transferred. Uploads without this field are always transferred. | No |
 | `permissions` | `string` | File permissions applied after upload, in octal notation (e.g. `"640"`, `"755"`). | No |
 | `owner` | `string` | File owner applied after upload, in `"user"` or `"user:group"` format (e.g. `"mosquitto"`, `"www-data:www-data"`). Requires the deploy user to have `sudo` or sufficient privileges. | No |
+| `exclude` | `string[]` | Glob patterns or paths to skip during directory upload (e.g. `".git"`, `"*.md"`, `"node_modules"`). Ignored for single-file uploads. | No |
+| `compress` | `boolean` | Compress the archive during transfer (default: `true`). Set to `false` for directories full of already-compressed files (JARs, ZIPs, images) to reduce CPU overhead without affecting transfer size. | No |
 
 `dest` must start with `/`. If `src` is a directory, `dest` is used as the destination directory and the relative structure is preserved.
 
@@ -150,6 +152,29 @@ services:
       - /opt/dockflow/monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
 ```
 
+## Upload-only projects
+
+Some projects have no Docker services — they only transfer files to a server. Use `no_services: true` to declare this explicitly:
+
+```yaml
+# .dockflow/config.yml
+project_name: my-project
+no_services: true
+
+upload:
+  - src: ./dist/
+    dest: /var/www/my-project/
+```
+
+With `no_services: true`:
+- Docker build and compose deploy are skipped entirely
+- Commands that require a running stack (`dockflow app logs`, `dockflow app status`, `rollback`, etc.) return a clear error instead of failing silently
+- Pre/post-deploy hooks still run
+
+<Callout type="warning">
+  Without `no_services: true`, a missing `docker-compose.yml` is treated as a configuration error and the deployment fails. Only set this flag when the project genuinely has no Docker services — not as a workaround for a misconfigured compose path.
+</Callout>
+
 ## See also
 
 - [Templates](/configuration/templates) — use `{{ current.env.xxx }}` inside transferred files via Nunjucks rendering