feat(env): improve support for instances without internet connection (#3915)

packages/common/env.ts

@@ -1,7 +1,7 @@
 import { randomBytes } from "crypto";
 import { z } from "zod/v4";
 
-import { createEnv } from "@homarr/core/infrastructure/env";
+import { createBooleanSchema, createEnv } from "@homarr/core/infrastructure/env";
 
 const errorSuffix = `, please generate a 64 character secret in hex format or use the following: "${randomBytes(32).toString("hex")}"`;
 
@@ -23,9 +23,11 @@ export const env = createEnv({
       .regex(/^[0-9a-fA-F]{64}$/, {
         message: `SECRET_ENCRYPTION_KEY must only contain hex characters${errorSuffix}`,
       }),
+    NO_EXTERNAL_CONNECTION: createBooleanSchema(false),
   },
   runtimeEnv: {
     SECRET_ENCRYPTION_KEY: process.env.SECRET_ENCRYPTION_KEY,
     NODE_ENV: process.env.NODE_ENV,
+    NO_EXTERNAL_CONNECTION: process.env.NO_EXTERNAL_CONNECTION,
   },
 });

packages/cron-jobs/src/jobs/analytics.ts

@@ -1,4 +1,5 @@
 import { sendServerAnalyticsAsync } from "@homarr/analytics";
+import { env } from "@homarr/common/env";
 import { EVERY_WEEK } from "@homarr/cron-jobs-core/expressions";
 import { db } from "@homarr/db";
 import { getServerSettingByKeyAsync } from "@homarr/db/queries";
@@ -9,6 +10,7 @@ export const analyticsJob = createCronJob("analytics", EVERY_WEEK, {
   runOnStart: true,
   preventManualExecution: true,
 }).withCallback(async () => {
+  if (env.NO_EXTERNAL_CONNECTION) return;
   const analyticSetting = await getServerSettingByKeyAsync(db, "analytics");
 
   if (!analyticSetting.enableGeneral) {

packages/cron-jobs/src/jobs/icons-updater.ts

@@ -1,4 +1,5 @@
 import { createId, splitToNChunks, Stopwatch } from "@homarr/common";
+import { env } from "@homarr/common/env";
 import { EVERY_WEEK } from "@homarr/cron-jobs-core/expressions";
 import type { InferInsertModel } from "@homarr/db";
 import { db, handleTransactionsAsync, inArray, sql } from "@homarr/db";
@@ -12,6 +13,8 @@ export const iconsUpdaterJob = createCronJob("iconsUpdater", EVERY_WEEK, {
   runOnStart: true,
   expectedMaximumDurationInMillis: 10 * 1000,
 }).withCallback(async () => {
+  if (env.NO_EXTERNAL_CONNECTION) return;
+
   logger.info("Updating icon repository cache...");
   const stopWatch = new Stopwatch();
   const repositoryIconGroups = await fetchIconsAsync();

packages/request-handler/src/update-checker.ts

@@ -3,6 +3,7 @@ import { Octokit } from "octokit";
 import { compareSemVer, isValidSemVer } from "semver-parser";
 
 import { fetchWithTimeout } from "@homarr/common";
+import { env } from "@homarr/common/env";
 import { logger } from "@homarr/log";
 import { createChannelWithLatestAndEvents } from "@homarr/redis";
 import { createCachedRequestHandler } from "@homarr/request-handler/lib/cached-request-handler";
@@ -13,6 +14,11 @@ export const updateCheckerRequestHandler = createCachedRequestHandler({
   queryKey: "homarr-update-checker",
   cacheDuration: dayjs.duration(1, "hour"),
   async requestAsync(_) {
+    if (env.NO_EXTERNAL_CONNECTION)
+      return {
+        availableUpdates: [],
+      };
+
     const octokit = new Octokit({
       request: {
         fetch: fetchWithTimeout,