docs(advanced): custom Dockerfile (#435)

felangel · web-flow · commit 22c624e82573 · 2022-11-29T10:31:40.000-06:00
diff --git a/.github/workflows/.docker_tests.yaml b/.github/workflows/.docker_tests.yaml
@@ -7,6 +7,10 @@ on:
         required: false
         type: string
         default: ""
+      docker_directory:
+        required: false
+        type: string
+        default: "build"
       test_directory:
         required: false
         type: string
@@ -41,7 +45,7 @@ jobs:
         run: dart_frog build
 
       - name: 🐳 Build Docker Image
-        run: docker build -q build -t e2e-image
+        run: docker build -q ${{inputs.docker_directory}} -t e2e-image
 
       - name: ⚡️ Run Docker Image
         run: docker run -d -p 8080:8080 --name e2e --rm e2e-image
diff --git a/.github/workflows/examples_kitchen_sink.yaml b/.github/workflows/examples_kitchen_sink.yaml
@@ -32,3 +32,10 @@ jobs:
     with:
       setup: rm pubspec_overrides.yaml && dart pub global activate --source path ../../packages/dart_frog_cli
       working_directory: examples/kitchen_sink
+
+  docker_custom:
+    uses: ./.github/workflows/.docker_tests.yaml
+    with:
+      setup: rm pubspec_overrides.yaml && dart pub global activate --source path ../../packages/dart_frog_cli
+      docker_directory: .
+      working_directory: examples/kitchen_sink
diff --git a/docs/docs/advanced/custom_dockerfile.md b/docs/docs/advanced/custom_dockerfile.md
@@ -0,0 +1,74 @@
+---
+sidebar_position: 2
+title: 🐳 Custom Dockerfile
+---
+
+<!-- cSpell:ignore WORKDIR -->
+
+# Custom Dockerfile 🐳
+
+A `Dockerfile` is automatically generated when creating a production build via the `dart_frog build` command.
+
+To use a custom `Dockerfile`, you can create a `Dockerfile` at the root of the project.
+
+```
+├── Dockerfile <-- NEW
+├── README.md
+├── analysis_options.yaml
+├── pubspec.lock
+├── pubspec.yaml
+├── routes
+│   └── index.dart
+└── test
+    └── routes
+        └── index_test.dart
+```
+
+The following `Dockerfile` is a good starting point:
+
+```dockerfile
+# An example of using a custom Dockerfile with Dart Frog
+# Official Dart image: https://hub.docker.com/_/dart
+# Specify the Dart SDK base image version using dart:<version> (ex: dart:2.17)
+FROM dart:stable AS build
+
+WORKDIR /app
+
+# Resolve app dependencies.
+COPY pubspec.* ./
+RUN dart pub get
+
+# Copy app source code and AOT compile it.
+COPY . .
+
+# Generate a production build.
+RUN dart pub global activate dart_frog_cli
+RUN dart pub global run dart_frog_cli:dart_frog build
+
+# Ensure packages are still up-to-date if anything has changed.
+RUN dart pub get --offline
+RUN dart compile exe build/bin/server.dart -o build/bin/server
+
+# Build minimal serving image from AOT-compiled `/server` and required system
+# libraries and configuration files stored in `/runtime/` from the build stage.
+FROM scratch
+COPY --from=build /runtime/ /
+COPY --from=build /app/build/bin/server /app/bin/
+# Uncomment the following line if you are serving static files.
+# COPY --from=build /app/build/public /public/
+
+# Start the server.
+CMD ["/app/bin/server"]
+```
+
+To build your Docker image run:
+
+```sh
+docker build . -t dart-frog-app
+```
+
+Then run your Docker container via:
+
+```sh
+docker run -i -t -p 8080:8080 dart-frog-app
+```
diff --git a/docs/docs/advanced/powered_by_header.md b/docs/docs/advanced/powered_by_header.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 2
+sidebar_position: 3
 title: 🔋 Powered By Header
 ---
 
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
@@ -153,7 +153,7 @@ const config = {
         copyright: `Copyright © ${new Date().getFullYear()} Very Good Ventures.<br/>Built with 💙 by <a target="_blank" rel="noopener" aria-label="Very Good Ventures" href="https://verygood.ventures">Very Good Ventures</a>.`,
       },
       prism: {
-        additionalLanguages: ['bash', 'dart', 'yaml'],
+        additionalLanguages: ['bash', 'dart', 'docker', 'yaml'],
         theme: lightCodeTheme,
         darkTheme: darkCodeTheme,
       },
diff --git a/docs/yarn.lock b/docs/yarn.lock
@@ -2958,9 +2958,9 @@ caniuse-api@^3.0.0:
     lodash.uniq "^4.5.0"
 
 caniuse-lite@^1.0.0, caniuse-lite@^1.0.30001335, caniuse-lite@^1.0.30001349:
-  version "1.0.30001355"
-  resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001355.tgz#e240b7177443ed0198c737a7f609536976701c77"
-  integrity sha512-Sd6pjJHF27LzCB7pT7qs+kuX2ndurzCzkpJl6Qct7LPSZ9jn0bkOA8mdgMgmqnQAWLVOOGjLpc+66V57eLtb1g==
+  version "1.0.30001434"
+  resolved "https://registry.npmjs.org/caniuse-lite/-/caniuse-lite-1.0.30001434.tgz"
+  integrity sha512-aOBHrLmTQw//WFa2rcF1If9fa3ypkC1wzqqiKHgfdrXTWcU8C4gKVZT77eQAPWN1APys3+uQ0Df07rKauXGEYA==
 
 ccount@^1.0.0:
   version "1.1.0"
diff --git a/examples/kitchen_sink/Dockerfile b/examples/kitchen_sink/Dockerfile
@@ -0,0 +1,31 @@
+# An example of using a custom Dockerfile with Dart Frog
+# Official Dart image: https://hub.docker.com/_/dart
+# Specify the Dart SDK base image version using dart:<version> (ex: dart:2.17)
+FROM dart:stable AS build
+
+WORKDIR /app
+
+# Resolve app dependencies.
+COPY pubspec.* ./
+RUN dart pub get
+
+# Copy app source code and AOT compile it.
+COPY . .
+
+# Generate a production build.
+RUN dart pub global activate dart_frog_cli
+RUN dart pub global run dart_frog_cli:dart_frog build
+
+# Ensure packages are still up-to-date if anything has changed.
+RUN dart pub get --offline
+RUN dart compile exe build/bin/server.dart -o build/bin/server
+
+# Build minimal serving image from AOT-compiled `/server` and required system
+# libraries and configuration files stored in `/runtime/` from the build stage.
+FROM scratch
+COPY --from=build /runtime/ /
+COPY --from=build /app/build/bin/server /app/bin/
+COPY --from=build /app/build/public /public/
+
+# Start the server.
+CMD ["/app/bin/server"]
diff --git a/packages/dart_frog_cli/e2e/test/dart_frog_build_test.dart b/packages/dart_frog_cli/e2e/test/dart_frog_build_test.dart
@@ -45,44 +45,6 @@ void main() {
       expect(path.basename(entities.first.path), equals(projectName));
     });
 
-    test('creates the project directory with a custom Dockerfile', () async {
-      final customDockerFileContents = '''
-# My Custom Dockerfile
-FROM dart:2.18 AS build
-
-WORKDIR /app
-
-COPY pubspec.* ./
-RUN dart pub get
-
-COPY . .
-
-RUN dart pub get --offline
-RUN dart compile exe bin/server.dart -o bin/server
-
-FROM scratch
-COPY --from=build /runtime/ /
-COPY --from=build /app/bin/server /app/bin/
-
-CMD ["/app/bin/server"]
-''';
-      final tempDirectory = Directory.systemTemp.createTempSync();
-      final projectDirectoryPath = path.join(tempDirectory.path, projectName);
-      final projectDirectory = Directory(projectDirectoryPath);
-      await dartFrogCreate(projectName: projectName, directory: tempDirectory);
-      File(
-        path.join(projectDirectoryPath, 'Dockerfile'),
-      ).writeAsStringSync(customDockerFileContents);
-      await dartFrogBuild(directory: projectDirectory);
-      expect(
-        File(
-          path.join(projectDirectoryPath, 'build', 'Dockerfile'),
-        ).readAsStringSync(),
-        equals(customDockerFileContents),
-      );
-      await tempDirectory.delete(recursive: true);
-    });
-
     testServer('GET / returns 200 with greeting', (host) async {
       final response = await http.get(Uri.parse(host));
       expect(response.statusCode, equals(HttpStatus.ok));
diff --git a/packages/dart_frog_cli/lib/src/commands/build/build.dart b/packages/dart_frog_cli/lib/src/commands/build/build.dart
@@ -47,7 +47,7 @@ class BuildCommand extends DartFrogCommand {
     final _ = await generator.generate(
       DirectoryGeneratorTarget(cwd),
       vars: vars,
-      fileConflictResolution: FileConflictResolution.skip,
+      fileConflictResolution: FileConflictResolution.overwrite,
     );
 
     logger.detail('[codegen] running post-gen...');
diff --git a/packages/dart_frog_cli/test/src/commands/build/build_test.dart b/packages/dart_frog_cli/test/src/commands/build/build_test.dart
@@ -65,7 +65,7 @@ void main() {
         () => generator.generate(
           any(),
           vars: any(named: 'vars'),
-          fileConflictResolution: FileConflictResolution.skip,
+          fileConflictResolution: FileConflictResolution.overwrite,
         ),
       ).thenAnswer((_) async => []);
       when(
