docs: update template contribution guidelines to reference external repository

feat(templates): support array-based environment variable configuration

CONTRIBUTING.md

@@ -165,86 +165,8 @@ Thank you for your contribution!
 
 ## Templates
 
-To add a new template, go to `templates` folder and create a new folder with the name of the template.
+To add a new template, go to `https://github.com/Dokploy/templates` repository and read the README.md file.
 
-Let's take the example of `plausible` template.
-
-1. create a folder in `templates/plausible`
-2. create a `docker-compose.yml` file inside the folder with the content of compose.
-3. create a `index.ts` file inside the folder with the following code as base:
-4. When creating a pull request, please provide a video of the template working in action.
-
-```typescript
-// EXAMPLE
-import {
-  generateBase64,
-  generateHash,
-  generateRandomDomain,
-  type Template,
-  type Schema,
-  type DomainSchema,
-} from "../utils";
-
-export function generate(schema: Schema): Template {
-  // do your stuff here, like create a new domain, generate random passwords, mounts.
-  const mainServiceHash = generateHash(schema.projectName);
-  const mainDomain = generateRandomDomain(schema);
-  const secretBase = generateBase64(64);
-  const toptKeyBase = generateBase64(32);
-
-  const domains: DomainSchema[] = [
-    {
-      host: mainDomain,
-      port: 8000,
-      serviceName: "plausible",
-    },
-  ];
-
-  const envs = [
-    `BASE_URL=http://${mainDomain}`,
-    `SECRET_KEY_BASE=${secretBase}`,
-    `TOTP_VAULT_KEY=${toptKeyBase}`,
-    `HASH=${mainServiceHash}`,
-  ];
-
-  const mounts: Template["mounts"] = [
-    {
-      filePath: "./clickhouse/clickhouse-config.xml",
-      content: "some content......",
-    },
-  ];
-
-  return {
-    envs,
-    mounts,
-    domains,
-  };
-}
-```
-
-4. Now you need to add the information about the template to the `templates/templates.ts` is a object with the following properties:
-
-**Make sure the id of the template is the same as the folder name and don't have any spaces, only slugified names and lowercase.**
-
-```typescript
-{
-	id: "plausible",
-	name: "Plausible",
-	version: "v2.1.0",
-	description:
-		"Plausible is a open source, self-hosted web analytics platform that lets you track website traffic and user behavior.",
-	logo: "plausible.svg", // we defined the name and the extension of the logo
-	links: {
-		github: "https://github.com/plausible/plausible",
-		website: "https://plausible.io/",
-		docs: "https://plausible.io/docs",
-	},
-	tags: ["analytics"],
-	load: () => import("./plausible/index").then((m) => m.generate),
-},
-```
-
-5. Add the logo or image of the template to `public/templates/plausible.svg`
 
 ### Recommendations
 

apps/dokploy/CONTRIBUTING.md

@@ -1,242 +0,0 @@
-
-
-# Contributing
-
-Hey, thanks for your interest in contributing to Dokploy! We appreciate your help and taking your time to contribute.
-
-
-Before you start, please first discuss the feature/bug you want to add with the owners and comunity via github issues.
-
-We have a few guidelines to follow when contributing to this project:
-
-- [Commit Convention](#commit-convention)
-- [Setup](#setup)
-- [Development](#development)
-- [Build](#build)
-- [Pull Request](#pull-request)
-
-## Commit Convention
-
-Before you craete a Pull Request, please make sure your commit message follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification.
-
-### Commit Message Format
-```
-<type>[optional scope]: <description>
-
-[optional body]
-
-[optional footer(s)]
-```
-
-#### Type
-Must be one of the following:
-
-* **feat**: A new feature
-* **fix**: A bug fix
-* **docs**: Documentation only changes
-* **style**: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
-* **refactor**: A code change that neither fixes a bug nor adds a feature
-* **perf**: A code change that improves performance
-* **test**: Adding missing tests or correcting existing tests
-* **build**: Changes that affect the build system or external dependencies (example scopes: gulp, broccoli, npm)
-* **ci**: Changes to our CI configuration files and scripts (example scopes: Travis, Circle, BrowserStack, SauceLabs)
-* **chore**: Other changes that don't modify `src` or `test` files
-* **revert**: Reverts a previous commit
-
-Example:
-```
-feat: add new feature
-```
-
-
-
-
-## Setup
-
-Before you start, please make the clone based on the `canary` branch, since the `main` branch is the source of truth and should always reflect the latest stable release, also the PRs will be merged to the `canary` branch.
-
-```bash
-git clone https://github.com/dokploy/dokploy.git
-cd dokploy
-pnpm install
-cp .env.example .env
-```
-
-## Development
-
-Is required to have **Docker** installed on your machine.
-
-
-### Setup
-
-Run the command that will spin up all the required services and files.
-
-```bash
-pnpm run setup
-```
-
-Now run the development server.
-
-```bash
-pnpm run dev
-```
-
-
-Go to http://localhost:3000 to see the development server
-
-## Build
-
-```bash
-pnpm run build
-```
-
-## Docker
-
-To build the docker image
-```bash
-pnpm run docker:build
-```
-
-To push the docker image
-```bash
-pnpm run docker:push
-```
-
-## Password Reset
-
-In the case you lost your password, you can reset it using the following command
-
-```bash
-pnpm run reset-password
-```
-
-If you want to test the webhooks on development mode using localtunnel, make sure to install `localtunnel`
-
-```bash
-bunx lt --port 3000
-```
-
-If you run into permission issues of docker run the following command
-
-```bash
-sudo chown -R USERNAME dokploy or sudo chown -R $(whoami) ~/.docker
-```
-
-## Application deploy
-
-In case you want to deploy the application on your machine and you selected nixpacks or buildpacks, you need to install first.
-
-```bash
-# Install Nixpacks
-curl -sSL https://nixpacks.com/install.sh -o install.sh \
-    && chmod +x install.sh \
-    && ./install.sh
-```
-
-```bash
-# Install Buildpacks
-curl -sSL "https://github.com/buildpacks/pack/releases/download/v0.32.1/pack-v0.32.1-linux.tgz" | tar -C /usr/local/bin/ --no-same-owner -xzv pack
-```
-
-
-## Pull Request
-
-- The `main` branch is the source of truth and should always reflect the latest stable release.
-- Create a new branch for each feature or bug fix.
-- Make sure to add tests for your changes.
-- Make sure to update the documentation for any changes Go to the [docs.dokploy.com](https://docs.dokploy.com) website to see the changes.
-- When creating a pull request, please provide a clear and concise description of the changes made.
-- If you include a video or screenshot, would be awesome so we can see the changes in action.
-- If your pull request fixes an open issue, please reference the issue in the pull request description.
-- Once your pull request is merged, you will be automatically added as a contributor to the project.
-
-Thank you for your contribution!
-
-
-
-
-
-## Templates
-
-To add a new template, go to `templates` folder and create a new folder with the name of the template.
-
-Let's take the example of `plausible` template.
-
-1. create a folder in `templates/plausible`
-2. create a `docker-compose.yml` file inside the folder with the content of compose.
-3. create a `index.ts` file inside the folder with the following code as base:
-4. When creating a pull request, please provide a video of the template working in action.
-
-```typescript
-// EXAMPLE
-import {
-	generateHash,
-	generateRandomDomain,
-	type Template,
-	type Schema,
-} from "../utils";
-
-
-export function generate(schema: Schema): Template {
-
-	// do your stuff here, like create a new domain, generate random passwords, mounts.
-	const mainServiceHash = generateHash(schema.projectName);
-	const randomDomain = generateRandomDomain(schema);
-	const secretBase = generateBase64(64);
-	const toptKeyBase = generateBase64(32);
-
-	const envs = [
-// If you want to show a domain in the UI, please add the prefix _HOST at the end of the variable name.
-		`PLAUSIBLE_HOST=${randomDomain}`,
-		"PLAUSIBLE_PORT=8000",
-		`BASE_URL=http://${randomDomain}`,
-		`SECRET_KEY_BASE=${secretBase}`,
-		`TOTP_VAULT_KEY=${toptKeyBase}`,
-		`HASH=${mainServiceHash}`,
-	];
-
-    const mounts: Template["mounts"] = [
-		{
-			mountPath: "./clickhouse/clickhouse-config.xml",
-			content: `some content......`,
-		},
-	];
-
-	return {
-		envs,
-        mounts,
-	};
-}
-```
-
-4. Now you need to add the information about the template to the `templates/templates.ts` is a object with the following properties:
-
-**Make sure the id of the template is the same as the folder name and don't have any spaces, only slugified names and lowercase.**
-
-```typescript
-{
-	id: "plausible",
-	name: "Plausible",
-	version: "v2.1.0",
-	description:
-		"Plausible is a open source, self-hosted web analytics platform that lets you track website traffic and user behavior.",
-	logo: "plausible.svg", // we defined the name and the extension of the logo
-	links: {
-		github: "https://github.com/plausible/plausible",
-		website: "https://plausible.io/",
-		docs: "https://plausible.io/docs",
-	},
-	tags: ["analytics"],
-	load: () => import("./plausible/index").then((m) => m.generate),
-},
-```
-
-5. Add the logo or image of the template to `public/templates/plausible.svg`
-
-
-### Recomendations
-- Use the same name of the folder as the id of the template.
-- The logo should be in the public folder.
-- If you want to show a domain in the UI, please add the prefix _HOST at the end of the variable name.
-- Test first on a vps or a server to make sure the template works.
-

apps/dokploy/__test__/templates/config.template.test.ts

@@ -166,7 +166,38 @@ describe("processTemplate", () => {
 			if (!baseUrl || !secretKey) return;
 
 			expect(baseUrl).toContain(mockSchema.projectName);
-			expect(secretKey.split("=")[1]).toHaveLength(64);
+			const base64Value = secretKey.split("=")[1];
+			expect(base64Value).toBeDefined();
+			if (!base64Value) return;
+			expect(base64Value).toMatch(/^[A-Za-z0-9+/]+={0,2}$/);
+			expect(base64Value.length).toBeGreaterThanOrEqual(86);
+			expect(base64Value.length).toBeLessThanOrEqual(88);
+		});
+
+		it("should process env vars when provided as an array", () => {
+			const template: CompleteTemplate = {
+				metadata: {} as any,
+				variables: {},
+				config: {
+					domains: [],
+					env: [
+						'CLOUDFLARE_TUNNEL_TOKEN="<INSERT TOKEN>"',
+						'ANOTHER_VAR="some value"',
+						"DOMAIN=${domain}",
+					],
+					mounts: [],
+				},
+			};
+
+			const result = processTemplate(template, mockSchema);
+			expect(result.envs).toHaveLength(3);
+
+			// Should preserve exact format for static values
+			expect(result.envs[0]).toBe('CLOUDFLARE_TUNNEL_TOKEN="<INSERT TOKEN>"');
+			expect(result.envs[1]).toBe('ANOTHER_VAR="some value"');
+
+			// Should process variables in array items
+			expect(result.envs[2]).toContain(mockSchema.projectName);
 		});
 
 		it("should allow using utility functions directly in env vars", () => {
@@ -195,7 +226,12 @@ describe("processTemplate", () => {
 			if (!randomDomainEnv || !secretKeyEnv) return;
 
 			expect(randomDomainEnv).toContain(mockSchema.projectName);
-			expect(secretKeyEnv.split("=")[1]).toHaveLength(32);
+			const base64Value = secretKeyEnv.split("=")[1];
+			expect(base64Value).toBeDefined();
+			if (!base64Value) return;
+			expect(base64Value).toMatch(/^[A-Za-z0-9+/]+={0,2}$/);
+			expect(base64Value.length).toBeGreaterThanOrEqual(42);
+			expect(base64Value.length).toBeLessThanOrEqual(44);
 		});
 	});
 
@@ -325,8 +361,22 @@ describe("processTemplate", () => {
 			if (!baseUrl || !secretKey || !totpKey) return;
 
 			expect(baseUrl).toContain(mockSchema.projectName);
-			expect(secretKey.split("=")[1]).toHaveLength(64);
-			expect(totpKey.split("=")[1]).toHaveLength(32);
+
+			// Check base64 lengths and format
+			const secretKeyValue = secretKey.split("=")[1];
+			const totpKeyValue = totpKey.split("=")[1];
+
+			expect(secretKeyValue).toBeDefined();
+			expect(totpKeyValue).toBeDefined();
+			if (!secretKeyValue || !totpKeyValue) return;
+
+			expect(secretKeyValue).toMatch(/^[A-Za-z0-9+/]+={0,2}$/);
+			expect(secretKeyValue.length).toBeGreaterThanOrEqual(86);
+			expect(secretKeyValue.length).toBeLessThanOrEqual(88);
+
+			expect(totpKeyValue).toMatch(/^[A-Za-z0-9+/]+={0,2}$/);
+			expect(totpKeyValue.length).toBeGreaterThanOrEqual(42);
+			expect(totpKeyValue.length).toBeLessThanOrEqual(44);
 
 			// Check mounts
 			expect(result.mounts).toHaveLength(1);
@@ -334,8 +384,8 @@ describe("processTemplate", () => {
 			expect(mount).toBeDefined();
 			if (!mount) return;
 			expect(mount.content).toContain(mockSchema.projectName);
-			expect(mount.content).toMatch(/secret=[A-Za-z0-9+/]{64}/);
-			expect(mount.content).toMatch(/totp=[A-Za-z0-9+/]{32}/);
+			expect(mount.content).toMatch(/secret=[A-Za-z0-9+/]{86,88}/);
+			expect(mount.content).toMatch(/totp=[A-Za-z0-9+/]{42,44}/);
 		});
 	});
 

apps/dokploy/components/dashboard/projects/show.tsx

@@ -186,7 +186,7 @@ export const ShowProjects = () => {
 																										target="_blank"
 																										href={`${domain.https ? "https" : "http"}://${domain.host}${domain.path}`}
 																									>
-																										<span>{domain.host}</span>
+																										<span className="truncate">{domain.host}</span>
 																										<ExternalLinkIcon className="size-4 shrink-0" />
 																									</Link>
 																								</DropdownMenuItem>
@@ -222,7 +222,7 @@ export const ShowProjects = () => {
 																										target="_blank"
 																										href={`${domain.https ? "https" : "http"}://${domain.host}${domain.path}`}
 																									>
-																										<span>{domain.host}</span>
+																										<span className="truncate">{domain.host}</span>
 																										<ExternalLinkIcon className="size-4 shrink-0" />
 																									</Link>
 																								</DropdownMenuItem>

apps/dokploy/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "dokploy",
-	"version": "v0.20.0",
+	"version": "v0.20.2",
 	"private": true,
 	"license": "Apache-2.0",
 	"type": "module",

apps/dokploy/server/api/routers/compose.ts

@@ -607,7 +607,7 @@ export const composeRouter = createTRPCRouter({
 
 				const processedTemplate = processTemplate(config, {
 					serverIp: serverIp,
-					projectName: compose.project.name,
+					projectName: compose.appName,
 				});
 
 				return {
@@ -676,7 +676,7 @@ export const composeRouter = createTRPCRouter({
 
 				const processedTemplate = processTemplate(config, {
 					serverIp: serverIp,
-					projectName: compose.project.name,
+					projectName: compose.appName,
 				});
 
 				// Update compose file

packages/server/src/setup/server-setup.ts

@@ -546,7 +546,7 @@ export const createTraefikInstance = () => {
 		if docker service inspect dokploy-traefik > /dev/null 2>&1; then
 			echo "Migrating Traefik to Standalone..."
 			docker service rm dokploy-traefik
-			sleep 7
+			sleep 8
 			echo "Traefik migrated to Standalone ✅"
 		fi
 			

packages/server/src/setup/traefik-setup.ts

@@ -91,9 +91,26 @@ export const initializeTraefik = async ({
 		try {
 			const service = docker.getService("dokploy-traefik");
 			await service?.remove({ force: true });
-			await new Promise((resolve) => setTimeout(resolve, 5000));
-		} catch (_) {}
 
+			let attempts = 0;
+			const maxAttempts = 5;
+			while (attempts < maxAttempts) {
+				try {
+					await docker.listServices({
+						filters: { name: ["dokploy-traefik"] },
+					});
+					console.log("Waiting for service cleanup...");
+					await new Promise((resolve) => setTimeout(resolve, 5000));
+					attempts++;
+				} catch (e) {
+					break;
+				}
+			}
+		} catch (err) {
+			console.log("No existing service to remove");
+		}
+
+		// Then try to remove any existing container
 		const container = docker.getContainer(containerName);
 		try {
 			const inspect = await container.inspect();
@@ -103,15 +120,31 @@ export const initializeTraefik = async ({
 			}
 
 			await container.remove({ force: true });
+			await new Promise((resolve) => setTimeout(resolve, 5000));
 		} catch (error) {
-			console.log(error);
+			console.log("No existing container to remove");
 		}
 
-		await docker.createContainer(settings);
-		const newContainer = docker.getContainer(containerName);
-		await newContainer.start();
+		// Create and start the new container
+		try {
+			await docker.createContainer(settings);
+			const newContainer = docker.getContainer(containerName);
+			await newContainer.start();
+			console.log("Traefik container started successfully");
+		} catch (error: any) {
+			if (error?.json?.message?.includes("port is already allocated")) {
+				console.log("Ports still in use, waiting longer for cleanup...");
+				await new Promise((resolve) => setTimeout(resolve, 10000));
+				// Try one more time
+				await docker.createContainer(settings);
+				const newContainer = docker.getContainer(containerName);
+				await newContainer.start();
+				console.log("Traefik container started successfully after retry");
+			}
+		}
 	} catch (error) {
-		console.log(error);
+		console.error("Failed to initialize Traefik:", error);
+		throw error;
 	}
 };
 

packages/server/src/templates/index.ts

@@ -53,14 +53,12 @@ export const generatePassword = (quantity = 16): string => {
 };
 
 /**
- * Generate a random base64 string of specified length
+ * Generate a random base64 string from N random bytes
+ * @param bytes Number of random bytes to generate before base64 encoding (default: 32)
+ * @returns base64 encoded string of the random bytes
  */
-export function generateBase64(length: number): string {
-	// To get N characters in base64, we need to generate N * 3/4 bytes
-	const bytesNeeded = Math.ceil((length * 3) / 4);
-	return Buffer.from(randomBytes(bytesNeeded))
-		.toString("base64")
-		.substring(0, length);
+export function generateBase64(bytes = 32): string {
+	return randomBytes(bytes).toString("base64");
 }
 
 export function generateJwt(length = 256): string {

packages/server/src/templates/processors.ts

@@ -45,7 +45,7 @@ export interface CompleteTemplate {
 	variables: Record<string, string>;
 	config: {
 		domains: DomainConfig[];
-		env: Record<string, string>;
+		env: Record<string, string> | string[];
 		mounts?: MountConfig[];
 	};
 }
@@ -175,7 +175,8 @@ export function processDomains(
 	variables: Record<string, string>,
 	schema: Schema,
 ): Template["domains"] {
-	return template.config.domains.map((domain: DomainConfig) => ({
+	if (!template?.config?.domains) return [];
+	return template?.config?.domains?.map((domain: DomainConfig) => ({
 		...domain,
 		host: domain.host
 			? processValue(domain.host, variables, schema)
@@ -191,6 +192,19 @@ export function processEnvVars(
 	variables: Record<string, string>,
 	schema: Schema,
 ): Template["envs"] {
+	if (!template?.config?.env) return [];
+
+	// Handle array of env vars
+	if (Array.isArray(template.config.env)) {
+		return template.config.env.map((env) => {
+			if (typeof env === "string") {
+				return processValue(env, variables, schema);
+			}
+			return env;
+		});
+	}
+
+	// Handle object of env vars
 	return Object.entries(template.config.env).map(
 		([key, value]: [string, string]) => {
 			const processedValue = processValue(value, variables, schema);
@@ -207,9 +221,9 @@ export function processMounts(
 	variables: Record<string, string>,
 	schema: Schema,
 ): Template["mounts"] {
-	if (!template.config.mounts) return [];
+	if (!template?.config?.mounts) return [];
 
-	return template.config.mounts.map((mount: MountConfig) => ({
+	return template?.config?.mounts?.map((mount: MountConfig) => ({
 		filePath: processValue(mount.filePath, variables, schema),
 		content: processValue(mount.content, variables, schema),
 	}));

packages/server/src/utils/backups/index.ts

@@ -212,6 +212,5 @@ export const keepLatestNBackups = async (
 		}
 	} catch (error) {
 		console.error(error);
-		throw error;
 	}
 };