diff --git a/articles/assets/20241110_srcbook_create.png b/articles/assets/20241110_srcbook_create.png new file mode 100644 index 00000000..8c7d9350 Binary files /dev/null and b/articles/assets/20241110_srcbook_create.png differ diff --git a/articles/assets/20241110_srcbook_running.png b/articles/assets/20241110_srcbook_running.png new file mode 100644 index 00000000..a16c5c66 Binary files /dev/null and b/articles/assets/20241110_srcbook_running.png differ diff --git a/guides/20240910_guide_srcbook.md b/guides/20240910_guide_srcbook.md new file mode 100644 index 00000000..5f1a536e --- /dev/null +++ b/guides/20240910_guide_srcbook.md @@ -0,0 +1,211 @@ +--- +title: "Interactive TypeScript Notebooks in Daytona with Srcbook" +description: "This guide will demonstrate how to integrate Srcbook, an interactive TypeScript notebook environment, with Daytona, allowing you to manage and deploy Workspaces — reproducible development environments based on standard OCI containers, with built-in support for the Dev Container standard." +date: 2024-09-11 +author: "Oreoluwa Ajayi" +--- + +# Interactive TypeScript Notebooks in Daytona with Srcbook + +## Introduction + +This guide will demonstrate how to integrate Srcbook, an interactive TypeScript notebook environment, with Daytona, a development environment management tool. This integration provides an efficient cloud-based interactive development environment for TypeScript projects. You'll learn how to set up and run Srcbook within a Daytona-managed container. + +### TL;DR + +- Set up a Daytona-managed development environment. +- Configure the development environment to auto-launch Srcbook. +- Run TypeScript notebooks interactively using Srcbook. +- Integrate Daytona and Srcbook for seamless project management. + +## Step 1: Preparations + +Before getting started, ensure you have the following prerequisites: + +- Docker installed and running on your system. [Install Docker](https://docs.docker.com/get-docker/) +- Daytona installed. You can follow the [Daytona Installation Guide](https://www.daytona.io/docs/install). +- Basic familiarity with `devcontainer.json` for setting up development containers. Learn more [here](https://code.visualstudio.com/docs/remote/create-dev-container). + +### Example Preparations + +- **Step 1.1**: Install Docker and verify it's running. + + ```bash + docker --version + ``` + + Confirm Docker is installed by running the above command. The output should display the Docker version. + +- **Step 1.2**: Install Daytona and ensure that Daytona is properly installed by verifying the `daytona` command is recognized. + +## Step 2: Main Process + +This section covers creating a starter repository, setting up a `devcontainer.json` file, and configuring Daytona to launch Srcbook. + +### Step 2.1: Creating a Starter Repository + +1. **Create a GitHub Repository**: Start by creating a new GitHub repository for your Srcbook project. +2. **Clone the Repository** to your local machine: + ```bash + git clone https://github.com//srcbook-project.git + cd srcbook-project + ``` + +### Step 2.2: Setting Up the `devcontainer.json` File + +In the root of your repository, create a `.devcontainer` directory and add the `devcontainer.json` file: + +```bash +mkdir .devcontainer +touch .devcontainer/devcontainer.json +``` + +Now, open the `devcontainer.json` file and add the following configuration: + +```json +{ + "name": "Srcbook Development", + "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20", + "postCreateCommand": "npm install -g srcbook", + "postAttachCommand": "srcbook start", + "forwardPorts": [2150] +} +``` + +- **Note:** +- _Post Commands_: Automatically install necessary packages and start Srcbook after the container is created. +- _Forward Ports_: Ensures Srcbook runs on `localhost:2150` as specified in the devcontainer.json file. + ![Port Forwarding](../guides/assets/20241207_forwarding_srcbook_port_to_localhost_img.png) + +### Step 2.3: Launching the Devcontainer and Daytona + +1. **Launch the Container**: Open the repository in VSCode, and it will prompt you to reopen the folder in a container. This will create the dev environment using the `devcontainer.json` configuration. + +2. **Start Daytona**: + Once inside the development container, start Daytona by running: + ```bash + daytona serve + ``` + Daytona will now be ready to manage the Srcbook project. + +### Step 2.4: Creating a New Srcbook Project + +With Daytona running and the environment set up, you can now create a repository with a devcontainer for Srcbook: + +### Step 2.5: Adding API Tools API Key + +To configure your development environment with the required API key, follow these steps: + +1. Go to the API tools dashboard. +2. Navigate to the "API Keys" section. +3. Click "Generate New Key" and copy the key. + +![Adding API Key](../guides/assets/20241207_setting_up_ai_tools_adding_api_keys_for_integration_img.png) + +#### Example + +```bash +daytona create https://github.com/oreoluwa212/srcbooks-devcontainer +``` + +![Daytona Setup Screenshot](../articles/assets/20241110_srcbook_create.png) + +This command will generate a new TypeScript notebook for interactive coding. + +### Step 2.5: Running Srcbook + +Once your interactive TypeScript notebook environment, you can proceed to open with your preferred IDE following this [daytona IDE docs](https://www.daytona.io/docs/usage/ide) +![Daytona Setup Screenshot](../articles/assets/20241110_srcbook_running.png) + +## Step 3: Confirmation + +To confirm that your setup is correct, ensure the following: + +- Docker engine is up and running. +- Daytona server is running, and you can check status at `localhost:3986/health` +- Your interactive notebook is up and ready for use. + +**Tip**: If you see any errors, review your `devcontainer.json` for misconfigurations, or restart Daytona using: + +```bash +daytona serve +``` + +## Step 4: Running Srcbook Project + +### 4.1 Access Methods + +- Open via Daytona web interface +- Use VSCode Remote Containers extension +- Access through forwarded port `localhost:2150` + +### 4.2 First Notebook + +Create a sample TypeScript notebook to verify setup: + +```typescript +const greet = (name: string) => `Hello, ${name}!`; +console.log(greet("Srcbook")); +``` + +### Sample TypeScript Srcbook Screenshot + +Below is an example of a TypeScript notebook in Srcbook. The screenshot demonstrates a simple `greet` function: + +![Srcbook Example](../guides/assets/20241207_sample_typescript_src_book_img.png) + +## Step 5: Tips for Effective Use + +### 5.1 Environment Management + +- Always use `.devcontainer.json` for consistent setups +- Commit and push notebook changes regularly to preserve your interactive coding progress +- Use environment variables for configuration, Use lock files (`package-lock.json` or `yarn.lock`) to ensure consistent environments +- Understand that Srcbook notebooks maintain state between cells, use this to create sequential, context-aware computational workflows +- Be mindful of memory usage in long-running notebooks, use `delete` or reassign large variables to free up memory + +### 5.2 Workspace Best Practices + +- Commit `devcontainer.json` to version control +- Use console.log() and breakpoints effectively in Srcbook +- Document any specific configuration or setup steps in a `README` +- Use Daytona's workspace management for team consistency +- Use GitHub Actions or similar tools to validate notebook execution +- Export notebook results as part of your documentation or reporting process + +### 5.3 Common Issues and Troubleshooting + +### Problem 1: Container Fails to Start + +**Solution**: Ensure that Docker is running on your machine. Run `docker ps` to verify the status. + +### Problem 2: Daytona Unable to Connect + +**Solution**: Check that Daytona is running correctly by using: + +```bash +daytona +# Check Daytona workspace status +daytona list + +# Restart workspace +daytona restart + +# View workspace logs +daytona logs +``` + +## Conclusion + +By following this guide, you’ve successfully integrated Srcbook with Daytona, creating an efficient cloud-based TypeScript notebook environment. This guide demonstrated how to integrate Srcbook with Daytona, creating a powerful, reproducible TypeScript notebook development environment. By following these steps, you can streamline your development workflow and ensure consistent, shareable coding experiences. + +Explore more advanced Srcbook features by visiting the [Srcbook Documentation](https://srcbook.com) and continue to refine your Daytona setup by reading through the [Daytona Documentation](https://www.daytona.io/docs). + +## References + +- [Srcbook GitHub Repository](https://github.com/srcbookdev/srcbook) +- [Srcbook Website](https://srcbook.com) +- [Daytona Documentation](https://www.daytona.io/docs) +- [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/) + +--- diff --git a/guides/assets/20241207_forwarding_srcbook_port_to_localhost_img.png b/guides/assets/20241207_forwarding_srcbook_port_to_localhost_img.png new file mode 100644 index 00000000..f0932082 Binary files /dev/null and b/guides/assets/20241207_forwarding_srcbook_port_to_localhost_img.png differ diff --git a/guides/assets/20241207_sample_typescript_src_book_img.png b/guides/assets/20241207_sample_typescript_src_book_img.png new file mode 100644 index 00000000..d712d744 Binary files /dev/null and b/guides/assets/20241207_sample_typescript_src_book_img.png differ diff --git a/guides/assets/20241207_setting_up_ai_tools_adding_api_keys_for_integration_img.png b/guides/assets/20241207_setting_up_ai_tools_adding_api_keys_for_integration_img.png new file mode 100644 index 00000000..7cbcaab3 Binary files /dev/null and b/guides/assets/20241207_setting_up_ai_tools_adding_api_keys_for_integration_img.png differ